Paket B1 aus #185 (E5 Punkte 1–2). Blockiert war es durch #187, das ist geschlossen. #189 (B2) baut auf diesem Befehl auf und erweitert ihn um zwei Regionen; die Struktur unten ist darauf ausgelegt.
Stand: abgeschlossen. Gebaut und publiziert als 9.0.0-beta.3 in 53383e7, verifiziert durch CI-Lauf 580 (verify mit Fresh-Instance-Replay, pwsh) und Release-Lauf 581, beide grün. Die Abschlussprüfung fand eine veraltete Stelle und zog sie in 9.0.0-beta.4, d644a1d, nach (Punkt 10); verifiziert durch CI-Lauf 582 und Release-Lauf 583, beide grün. Lokal: pytest 2379 bestanden/3 übersprungen, docs verify, instructions verify grün. Ein Release ist nicht geschnitten – das entscheidet der Betreiber.
Was gebaut wurde
Eine menschenlesbare Kommandoreferenz unter docs/reference/, vollständig aus den cli_contract.CommandRecord-Datensätzen generiert – dieselbe Quelle wie -h, wikitool -h und tools/CONTRACT.md, aber eine eigene Darstellung (Entscheidung E5 in #185), kein Verweis auf tools/CONTRACT.md. Sprache der Seiten: Englisch (AGENTS.md § File naming, Punkt 3; die Datensätze sind ohnehin englisch).
Neuer Befehl wikitool docs reference [--apply] in tools/chemenu/commands/docs_verify.py neben docs toc/docs prerequisites/docs contract, Pfad "docs reference" in cli_contract.GROUPS unter „Types, instructions and docs" direkt nach "docs contract". Ohne --apply Trockenlauf (listet die Dateien, die sich ändern würden), mit --apply schreiben; idempotent. Eigener CommandRecord mit Zusammenfassung, Synopsis, Eigenschaften (WRITE, idempotent, COUNTED), Notes, Failure, Beispielen, never, see_also.
Rendering in eigenem Modul tools/chemenu/reference_doc.py (neben install_doc.py; Abweichung vom Entwurf „neue Funktion in cli_contract.py"): es braucht toc.anchor für die Linkanker, und cli_contract soll nichts aus chemenu importieren. cli_contract bekam nur exit_status_entries(rec) (die (code, Ursache)-Paare, aus denen render_exit_status_lines jetzt formatiert).
Aufbau für #189:reference_doc.regions() ist die Liste von Region(path, name, render), die docs reference und der Stale-Check gemeinsam durchlaufen. #189 hängt dort zwei Einträge an.
Seiten und Marker.
docs/reference/commands/<slug>.md, eine je Eintrag in cli_contract.GROUPS. <slug> = reference_doc.group_slug: Gruppenname klein, jede Folge von Nicht-Alphanumerischem → -, Ränder getrimmt.
Jede Seite: # <Gruppenname>, ein handgeschriebener Kopfsatz, die Region <!-- wikitool:reference-commands -->…<!-- /wikitool:reference-commands -->. Kein group="…"-Attribut im Marker: blocks._NAME erlaubt nur [a-z][a-z0-9-]*, und die Gruppe folgt aus dem Dateinamen.
docs/reference/commands/README.md: Kopf von Hand, Region reference-commands-index – je Gruppe ## <Gruppe>, „Full records: [.md](.md)" und eine Liste - [](<slug>.md#<anker>) - <summary>; Anker über toc.anchor (neu, öffentlich), also wie im TOC.
docs/reference/exit-codes.md: Kopf von Hand, Region reference-exit-codes (Punkt 5).
docs reference --apply legt keine Seite und keinen Marker an, wie docs prerequisites: eine fehlende Seite oder ein fehlendes Markerpaar ist Exit 1 mit Dateipfad und Marker, und es wird dann gar nichts geschrieben.
Je Kommando rendert die Region (reference_doc.render_command): ## `` (##, nicht ### – die Seite hat # als Titel, das TOC soll eine Zeile je Kommando haben), summary, dann fette Labels Synopsis, Options (```text-Block; entfällt ohne Optionen), Examples (```bash), Behaviour (= notes), Properties, Exit codes (exit_status_entries, inkl. Code-0-Einträge und generischer 42-Zeile), See also.
Optionen über cli.options_texts(paths) (neu): baut den Kontext je Kommando vom Root aus mit make_context(..., resilient_parsing=True) und ruft cli.render_options_text (vorher _render_options_text) – byte-gleich mit dem OPTIONS-Abschnitt von -h, per Test belegt.
Eigenschaften: Changes files, Idempotent, Atomic, Counts toward the session call budget: yes|no|only when called with arguments, Can reach the network, und bei Gates Gates: … - see [exit codes and gates](../exit-codes.md).
Weggelassen werden die agentenadressierten Felder: jede Failure.reaction (nur cause bleibt) und never. Für die Agenten bleibt tools/CONTRACT.md vollständig.
exit-codes.md: ein fester Absatz, der AGENTS.md § Tool error contract und § Gates verlinkt, nicht kopiert; darunter „Gates by command" (je verschiedenem Properties.gates-String, wörtlich, die deklarierenden Kommandos mit Link) und „Exit 42 causes" (je Kommando jede Ursache mit Code 42).
TOC-Zusammenspiel: Die meisten Gruppenseiten liegen über 100 Zeilen und fallen unter toc.target_files(). reference_doc.refresh wendet nach der Region toc.upsert an. Beim Bauen gefunden und behoben:toc.upsert setzte das TOC vor die erste ##-Überschrift – auf diesen Seiten lag die innerhalb der generierten Region, das TOC wäre in die Region geraten und beim nächsten Lauf überschrieben worden. toc._first_level2_offset weicht jetzt auf den öffnenden Marker aus, wenn die erste ## in einer anderen <!-- wikitool:… -->-Region liegt (auf dem code-maskierten Text, damit Marker in Inline-Code nicht zählen). Keine bestehende Datei hat sich dadurch geändert.
Stale-Check check_reference_regions in docs verify (vor check_toc_regions): Regionsinhalt gegen das Generat (das TOC prüft weiter check_toc_regions, keine Doppelmeldung); fehlende Seite, fehlendes Markerpaar und eine Seite unter docs/reference/commands/ ohne Gruppe (außer README.md) sind Fehler mit Abhilfe. Ohne docs/ grün.docs verify-Datensatz: Note, zwei Failures, never, see_also, Erfolgszeile.
check_readmes_have_no_command_table: keine Codeänderung; der Docstring von command_table_free_readmes() sagt, warum docs/reference/commands/README.md nicht dazugehört (geprüfte Kopie).
Doku nachgezogen:tools/CONTRACT.md (Einleitung: drei Ansichten für Agenten, eine vierte für Menschen), Modul-Docstring cli_contract.py, tools/README.md § Adding a command (Schritt 3), instructions/dev/doc-pull-through.md (Zeile zum Kommandoverhalten), docs/reference/README.md (verlinkt Kommandoreferenz und Exit-Codes; Seitentypen bleiben bis #189 bei types describe), README.md § Documentation, docs contract-Datensatz (see_also).
Abschlussprüfung (stack-close): Der Modulbaum in tools/README.md nannte reference_doc.py nicht, und die Zeile zu cli_contract.py zählte nur drei Ansichten. Beides ist in 9.0.0-beta.4 nachgezogen. Geprüft und ohne Änderung geblieben: docs/explanation/language-boundaries.md, das die Kommandoreferenz schon als aus cli_contract generiert beschreibt; README.md § Maintenance, das den Wartungsplan in tools/CONTRACT.md meint; die Routing-Zeile in AGENTS.md, die tools/CONTRACT.md als Agentenreferenz nennt. Keine Installationsinstruktion war berührt.
Version
MINOR – neuer Befehl, neuer Check, neue Dateien; drop-in in beide Richtungen. Gebumpt mit version bump --minor --impact medium auf 9.0.0-beta.3 (der Kandidat stand schon auf MAJOR, nur der Zähler stieg), der Nachzieh-Bump aus Punkt 10 mit --patch --impact low auf 9.0.0-beta.4. CHANGES.md: Bump-Zeilen und Themenabschnitt „Kommandoreferenz für Menschen unter docs/reference/ (#188)".
Akzeptanzkriterien
Für jeden Eintrag in cli_contract.GROUPS existiert genau eine docs/reference/commands/<slug>.md, und jede registrierte Kommandopfad-Zeichenkette erscheint genau einmal als ## `` in genau einer davon (test_every_group_has_one_page_and_every_command_one_section).
Keine generierte Seite enthält eine nicht leere Failure.reaction oder einen never-Text (test_no_page_carries_an_agent_addressed_field, echter Baum; test_a_generated_page_leaves_out_reactions_and_never, Fixture).
docs reference --apply zweimal hintereinander: der zweite Lauf ändert nichts; nach dem ersten meldet docs verify weder eine veraltete Referenzregion noch ein veraltetes TOC (test_apply_twice_changes_nothing_the_second_time, test_a_long_page_gets_its_toc_outside_the_generated_region).
Ein geänderter Datensatz ohne --apply lässt docs verify mit einer Meldung scheitern, die die Datei und docs reference --apply nennt (test_a_changed_record_makes_verify_name_the_page_and_the_command).
Der handgeschriebene Kopf einer Seite ist nach --apply byte-gleich (test_the_head_survives_apply_byte_for_byte).
Eine Gruppe ohne Seite und eine Seite ohne Gruppe lassen docs verify scheitern; docs reference --apply legt in beiden Fällen nichts an und endet bei fehlender Seite mit Exit 1, das die Datei nennt (test_a_group_without_a_page_fails_and_nothing_is_created, test_a_page_without_a_group_fails, test_a_page_without_its_marker_pair_fails_and_is_left_alone).
Ein Baum ohne docs/ besteht den neuen Check (test_a_tree_without_docs_passes).
exit-codes.md nennt jeden String, den ein Datensatz in Properties.gates deklariert, verlinkt AGENTS.md#tool-error-contract und AGENTS.md#gates und enthält keinen Satz aus diesen beiden Abschnitten (test_exit_codes_names_every_gate_and_links_rather_than_repeats_agents_md).
Das TOC einer langen Gruppenseite steht vor der generierten Region, nicht in ihr (test_a_long_page_gets_its_toc_outside_the_generated_region).
Exportiert (dist export) sind die Seiten unverändert gegenüber dem Ursprungs-Repo (test_the_reference_pages_survive_dist_export_unchanged), und docs verify ist im Zielbaum grün (CI-Schritt „The distribution works as a fresh instance" in den Läufen 580 und 582).
pytest, docs verify, instructions verify lokal grün; CI-Läufe 580 und 582 und Release-Läufe 581 und 583 grün.
Tests: tools/chemenu/tests/test_reference_doc.py (19 Tests – echter Baum und Fixture-Baum).
Nicht in diesem Paket
Skill-Katalog und Seitentypen-Referenz (#189, erweitert diesen Befehl).
Gate-Liste: AGENTS.md § Gates nennt fünf Gates (darunter das Iteration Budget, das mit 1 statt 42 endet), die Datensätze deklarieren sechs Namen (rebase-review, human-intervention-required stehen nicht in § Gates, instructions/gates.md nennt rebase-review aber). Diese Abweichung bestand schon vor diesem Paket; die generierte Seite zeigt nur, was die Datensätze sagen. Weiterverfolgt in #194.
Paket B1 aus #185 (E5 Punkte 1–2). Blockiert war es durch #187, das ist geschlossen. #189 (B2) baut auf diesem Befehl auf und erweitert ihn um zwei Regionen; die Struktur unten ist darauf ausgelegt.
**Stand: abgeschlossen.** Gebaut und publiziert als **9.0.0-beta.3** in `53383e7`, verifiziert durch CI-Lauf [580](https://gitea.nehmer.net/torben/chemenu/actions/runs/580) (`verify` mit Fresh-Instance-Replay, `pwsh`) und Release-Lauf [581](https://gitea.nehmer.net/torben/chemenu/actions/runs/581), beide grün. Die Abschlussprüfung fand eine veraltete Stelle und zog sie in **9.0.0-beta.4**, `d644a1d`, nach (Punkt 10); verifiziert durch CI-Lauf [582](https://gitea.nehmer.net/torben/chemenu/actions/runs/582) und Release-Lauf [583](https://gitea.nehmer.net/torben/chemenu/actions/runs/583), beide grün. Lokal: `pytest` 2379 bestanden/3 übersprungen, `docs verify`, `instructions verify` grün. Ein Release ist nicht geschnitten – das entscheidet der Betreiber.
## Was gebaut wurde
Eine menschenlesbare Kommandoreferenz unter `docs/reference/`, vollständig aus den `cli_contract.CommandRecord`-Datensätzen generiert – dieselbe Quelle wie `-h`, `wikitool -h` und `tools/CONTRACT.md`, aber eine **eigene Darstellung** (Entscheidung E5 in #185), kein Verweis auf `tools/CONTRACT.md`. Sprache der Seiten: Englisch (`AGENTS.md` § File naming, Punkt 3; die Datensätze sind ohnehin englisch).
1. **Neuer Befehl `wikitool docs reference [--apply]`** in `tools/chemenu/commands/docs_verify.py` neben `docs toc`/`docs prerequisites`/`docs contract`, Pfad `"docs reference"` in `cli_contract.GROUPS` unter „Types, instructions and docs" direkt nach `"docs contract"`. Ohne `--apply` Trockenlauf (listet die Dateien, die sich ändern würden), mit `--apply` schreiben; idempotent. Eigener `CommandRecord` mit Zusammenfassung, Synopsis, Eigenschaften (`WRITE`, idempotent, `COUNTED`), Notes, Failure, Beispielen, `never`, `see_also`.
- **Rendering in eigenem Modul `tools/chemenu/reference_doc.py`** (neben `install_doc.py`; Abweichung vom Entwurf „neue Funktion in `cli_contract.py`"): es braucht `toc.anchor` für die Linkanker, und `cli_contract` soll nichts aus `chemenu` importieren. `cli_contract` bekam nur `exit_status_entries(rec)` (die `(code, Ursache)`-Paare, aus denen `render_exit_status_lines` jetzt formatiert).
- **Aufbau für #189:** `reference_doc.regions()` ist die Liste von `Region(path, name, render)`, die `docs reference` und der Stale-Check gemeinsam durchlaufen. #189 hängt dort zwei Einträge an.
2. **Seiten und Marker.**
- `docs/reference/commands/<slug>.md`, eine je Eintrag in `cli_contract.GROUPS`. `<slug>` = `reference_doc.group_slug`: Gruppenname klein, jede Folge von Nicht-Alphanumerischem → `-`, Ränder getrimmt.
- Jede Seite: `# <Gruppenname>`, ein **handgeschriebener Kopfsatz**, die Region `<!-- wikitool:reference-commands -->…<!-- /wikitool:reference-commands -->`. **Kein `group="…"`-Attribut im Marker**: `blocks._NAME` erlaubt nur `[a-z][a-z0-9-]*`, und die Gruppe folgt aus dem Dateinamen.
- `docs/reference/commands/README.md`: Kopf von Hand, Region `reference-commands-index` – je Gruppe `## <Gruppe>`, „Full records: [<slug>.md](<slug>.md)" und eine Liste `- [`<pfad>`](<slug>.md#<anker>) - <summary>`; Anker über `toc.anchor` (neu, öffentlich), also wie im TOC.
- `docs/reference/exit-codes.md`: Kopf von Hand, Region `reference-exit-codes` (Punkt 5).
- **`docs reference --apply` legt keine Seite und keinen Marker an**, wie `docs prerequisites`: eine fehlende Seite oder ein fehlendes Markerpaar ist Exit 1 mit Dateipfad und Marker, und es wird dann gar nichts geschrieben.
3. **Je Kommando rendert die Region** (`reference_doc.render_command`): `## `<pfad>`` (**`##`, nicht `###`** – die Seite hat `#` als Titel, das TOC soll eine Zeile je Kommando haben), `summary`, dann fette Labels **Synopsis**, **Options** (```` ```text ````-Block; entfällt ohne Optionen), **Examples** (```` ```bash ````), **Behaviour** (= `notes`), **Properties**, **Exit codes** (`exit_status_entries`, inkl. Code-0-Einträge und generischer 42-Zeile), **See also**.
- Optionen über `cli.options_texts(paths)` (neu): baut den Kontext je Kommando vom Root aus mit `make_context(..., resilient_parsing=True)` und ruft `cli.render_options_text` (vorher `_render_options_text`) – byte-gleich mit dem OPTIONS-Abschnitt von `-h`, per Test belegt.
- Eigenschaften: `Changes files`, `Idempotent`, `Atomic`, `Counts toward the session call budget: yes|no|only when called with arguments`, `Can reach the network`, und bei Gates `Gates: … - see [exit codes and gates](../exit-codes.md)`.
4. **Weggelassen** werden die agentenadressierten Felder: jede `Failure.reaction` (nur `cause` bleibt) und `never`. Für die Agenten bleibt `tools/CONTRACT.md` vollständig.
5. **`exit-codes.md`:** ein fester Absatz, der `AGENTS.md` § Tool error contract und § Gates **verlinkt, nicht kopiert**; darunter „Gates by command" (je verschiedenem `Properties.gates`-String, wörtlich, die deklarierenden Kommandos mit Link) und „Exit 42 causes" (je Kommando jede Ursache mit Code 42).
6. **TOC-Zusammenspiel:** Die meisten Gruppenseiten liegen über 100 Zeilen und fallen unter `toc.target_files()`. `reference_doc.refresh` wendet nach der Region `toc.upsert` an. **Beim Bauen gefunden und behoben:** `toc.upsert` setzte das TOC vor die erste `##`-Überschrift – auf diesen Seiten lag die *innerhalb* der generierten Region, das TOC wäre in die Region geraten und beim nächsten Lauf überschrieben worden. `toc._first_level2_offset` weicht jetzt auf den öffnenden Marker aus, wenn die erste `##` in einer anderen `<!-- wikitool:… -->`-Region liegt (auf dem code-maskierten Text, damit Marker in Inline-Code nicht zählen). Keine bestehende Datei hat sich dadurch geändert.
7. **Stale-Check `check_reference_regions`** in `docs verify` (vor `check_toc_regions`): Regionsinhalt gegen das Generat (das TOC prüft weiter `check_toc_regions`, keine Doppelmeldung); fehlende Seite, fehlendes Markerpaar und eine Seite unter `docs/reference/commands/` ohne Gruppe (außer `README.md`) sind Fehler mit Abhilfe. **Ohne `docs/` grün.** `docs verify`-Datensatz: Note, zwei Failures, `never`, `see_also`, Erfolgszeile.
8. **`check_readmes_have_no_command_table`: keine Codeänderung**; der Docstring von `command_table_free_readmes()` sagt, warum `docs/reference/commands/README.md` nicht dazugehört (geprüfte Kopie).
9. **Doku nachgezogen:** `tools/CONTRACT.md` (Einleitung: drei Ansichten für Agenten, eine vierte für Menschen), Modul-Docstring `cli_contract.py`, `tools/README.md` § Adding a command (Schritt 3), `instructions/dev/doc-pull-through.md` (Zeile zum Kommandoverhalten), `docs/reference/README.md` (verlinkt Kommandoreferenz und Exit-Codes; Seitentypen bleiben bis #189 bei `types describe`), `README.md` § Documentation, `docs contract`-Datensatz (`see_also`).
10. **Abschlussprüfung (`stack-close`):** Der Modulbaum in `tools/README.md` nannte `reference_doc.py` nicht, und die Zeile zu `cli_contract.py` zählte nur drei Ansichten. Beides ist in 9.0.0-beta.4 nachgezogen. Geprüft und ohne Änderung geblieben: `docs/explanation/language-boundaries.md`, das die Kommandoreferenz schon als aus `cli_contract` generiert beschreibt; `README.md` § Maintenance, das den Wartungsplan in `tools/CONTRACT.md` meint; die Routing-Zeile in `AGENTS.md`, die `tools/CONTRACT.md` als Agentenreferenz nennt. Keine Installationsinstruktion war berührt.
## Version
**MINOR** – neuer Befehl, neuer Check, neue Dateien; drop-in in beide Richtungen. Gebumpt mit `version bump --minor --impact medium` auf **`9.0.0-beta.3`** (der Kandidat stand schon auf MAJOR, nur der Zähler stieg), der Nachzieh-Bump aus Punkt 10 mit `--patch --impact low` auf **`9.0.0-beta.4`**. `CHANGES.md`: Bump-Zeilen und Themenabschnitt „Kommandoreferenz für Menschen unter `docs/reference/` (#188)".
## Akzeptanzkriterien
- [x] Für jeden Eintrag in `cli_contract.GROUPS` existiert genau eine `docs/reference/commands/<slug>.md`, und jede registrierte Kommandopfad-Zeichenkette erscheint genau einmal als `## `<pfad>`` in genau einer davon (`test_every_group_has_one_page_and_every_command_one_section`).
- [x] Keine generierte Seite enthält eine nicht leere `Failure.reaction` oder einen `never`-Text (`test_no_page_carries_an_agent_addressed_field`, echter Baum; `test_a_generated_page_leaves_out_reactions_and_never`, Fixture).
- [x] `docs reference --apply` zweimal hintereinander: der zweite Lauf ändert nichts; nach dem ersten meldet `docs verify` weder eine veraltete Referenzregion noch ein veraltetes TOC (`test_apply_twice_changes_nothing_the_second_time`, `test_a_long_page_gets_its_toc_outside_the_generated_region`).
- [x] Ein geänderter Datensatz ohne `--apply` lässt `docs verify` mit einer Meldung scheitern, die die Datei und `docs reference --apply` nennt (`test_a_changed_record_makes_verify_name_the_page_and_the_command`).
- [x] Der handgeschriebene Kopf einer Seite ist nach `--apply` byte-gleich (`test_the_head_survives_apply_byte_for_byte`).
- [x] Eine Gruppe ohne Seite und eine Seite ohne Gruppe lassen `docs verify` scheitern; `docs reference --apply` legt in beiden Fällen nichts an und endet bei fehlender Seite mit Exit 1, das die Datei nennt (`test_a_group_without_a_page_fails_and_nothing_is_created`, `test_a_page_without_a_group_fails`, `test_a_page_without_its_marker_pair_fails_and_is_left_alone`).
- [x] Ein Baum ohne `docs/` besteht den neuen Check (`test_a_tree_without_docs_passes`).
- [x] `exit-codes.md` nennt jeden String, den ein Datensatz in `Properties.gates` deklariert, verlinkt `AGENTS.md#tool-error-contract` und `AGENTS.md#gates` und enthält keinen Satz aus diesen beiden Abschnitten (`test_exit_codes_names_every_gate_and_links_rather_than_repeats_agents_md`).
- [x] Das TOC einer langen Gruppenseite steht vor der generierten Region, nicht in ihr (`test_a_long_page_gets_its_toc_outside_the_generated_region`).
- [x] Exportiert (`dist export`) sind die Seiten unverändert gegenüber dem Ursprungs-Repo (`test_the_reference_pages_survive_dist_export_unchanged`), und `docs verify` ist im Zielbaum grün (CI-Schritt „The distribution works as a fresh instance" in den Läufen 580 und 582).
- [x] `pytest`, `docs verify`, `instructions verify` lokal grün; CI-Läufe 580 und 582 und Release-Läufe 581 und 583 grün.
Tests: `tools/chemenu/tests/test_reference_doc.py` (19 Tests – echter Baum und Fixture-Baum).
## Nicht in diesem Paket
- Skill-Katalog und Seitentypen-Referenz (#189, erweitert diesen Befehl).
- Gate-Liste: `AGENTS.md` § Gates nennt fünf Gates (darunter das Iteration Budget, das mit 1 statt 42 endet), die Datensätze deklarieren sechs Namen (`rebase-review`, `human-intervention-required` stehen nicht in § Gates, `instructions/gates.md` nennt `rebase-review` aber). Diese Abweichung bestand schon vor diesem Paket; die generierte Seite zeigt nur, was die Datensätze sagen. Weiterverfolgt in #194.
Changelog: Gegen den Baum 01c888d geprüft. status/blocked entfernt, weil #187 geschlossen ist. Korrigiert: Marker ohne group=-Attribut (blocks._NAME erlaubt keins), Kommandos als ## statt ###, Abschnitt „Tools Integration“ → README.md § Documentation, und Punkt 7 (check_readmes_have_no_command_table) braucht keine Codeänderung, nur einen Kommentar. Neu: --apply legt keine Seiten an (wie docs prerequisites); TOC-Zusammenspiel (toc.upsert im selben Lauf); ohne docs/ grün; Wortlaut für die Eigenschaften (jetzt auch atomic und network); Optionen über eine öffentliche Fassung von cli._render_options_text; Eintragsliste als Erweiterungspunkt für #189; Version auf den laufenden 9.0.0-Kandidaten bezogen. Die vorhandene Abweichung zwischen der Gate-Liste in AGENTS.md und den Datensätzen ist ausdrücklich nicht Teil dieses Pakets.
**Changelog:** Gegen den Baum `01c888d` geprüft. `status/blocked` entfernt, weil #187 geschlossen ist. Korrigiert: Marker ohne `group=`-Attribut (`blocks._NAME` erlaubt keins), Kommandos als `##` statt `###`, Abschnitt „Tools Integration“ → `README.md` § Documentation, und Punkt 7 (`check_readmes_have_no_command_table`) braucht keine Codeänderung, nur einen Kommentar. Neu: `--apply` legt keine Seiten an (wie `docs prerequisites`); TOC-Zusammenspiel (`toc.upsert` im selben Lauf); ohne `docs/` grün; Wortlaut für die Eigenschaften (jetzt auch `atomic` und `network`); Optionen über eine öffentliche Fassung von `cli._render_options_text`; Eintragsliste als Erweiterungspunkt für #189; Version auf den laufenden 9.0.0-Kandidaten bezogen. Die vorhandene Abweichung zwischen der Gate-Liste in `AGENTS.md` und den Datensätzen ist ausdrücklich nicht Teil dieses Pakets.
Changelog: Gebaut und publiziert als 9.0.0-beta.3 in 53383e7; CI-Lauf 580 und Release-Lauf 581 grün. Alle Akzeptanzkriterien abgehakt, jeweils mit dem Test, der sie belegt. Abweichungen vom Entwurf, im Body eingetragen: Das Rendering liegt in einem neuen Modul reference_doc.py statt in cli_contract.py. Hinzugekommen ist eine Korrektur in toc.py: Das TOC landet nie mehr in einer anderen generierten Region, auch das ist ein neues Kriterium mit Test. Der Stale-Check vergleicht nur den Regionsinhalt; das TOC prüft weiterhin check_toc_regions. Neu sind außerdem cli.options_texts und toc.anchor.
**Changelog:** Gebaut und publiziert als `9.0.0-beta.3` in `53383e7`; CI-Lauf 580 und Release-Lauf 581 grün. Alle Akzeptanzkriterien abgehakt, jeweils mit dem Test, der sie belegt. Abweichungen vom Entwurf, im Body eingetragen: Das Rendering liegt in einem neuen Modul `reference_doc.py` statt in `cli_contract.py`. Hinzugekommen ist eine Korrektur in `toc.py`: Das TOC landet nie mehr in einer anderen generierten Region, auch das ist ein neues Kriterium mit Test. Der Stale-Check vergleicht nur den Regionsinhalt; das TOC prüft weiterhin `check_toc_regions`. Neu sind außerdem `cli.options_texts` und `toc.anchor`.
Changelog: Body in den Endzustand gebracht. Neu ist Punkt 10 (Abschlussprüfung): Der Modulbaum in tools/README.md ist nachgezogen, als 9.0.0-beta.4 in d644a1d; CI-Lauf 582 und Release-Lauf 583 sind grün. Die übrigen geprüften Dokumente sind benannt und blieben unverändert. Damit geschlossen.
**Changelog:** Body in den Endzustand gebracht. Neu ist Punkt 10 (Abschlussprüfung): Der Modulbaum in `tools/README.md` ist nachgezogen, als 9.0.0-beta.4 in `d644a1d`; CI-Lauf 582 und Release-Lauf 583 sind grün. Die übrigen geprüften Dokumente sind benannt und blieben unverändert. Damit geschlossen.
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.
Paket B1 aus #185 (E5 Punkte 1–2). Blockiert war es durch #187, das ist geschlossen. #189 (B2) baut auf diesem Befehl auf und erweitert ihn um zwei Regionen; die Struktur unten ist darauf ausgelegt.
Stand: abgeschlossen. Gebaut und publiziert als 9.0.0-beta.3 in
53383e7, verifiziert durch CI-Lauf 580 (verifymit Fresh-Instance-Replay,pwsh) und Release-Lauf 581, beide grün. Die Abschlussprüfung fand eine veraltete Stelle und zog sie in 9.0.0-beta.4,d644a1d, nach (Punkt 10); verifiziert durch CI-Lauf 582 und Release-Lauf 583, beide grün. Lokal:pytest2379 bestanden/3 übersprungen,docs verify,instructions verifygrün. Ein Release ist nicht geschnitten – das entscheidet der Betreiber.Was gebaut wurde
Eine menschenlesbare Kommandoreferenz unter
docs/reference/, vollständig aus dencli_contract.CommandRecord-Datensätzen generiert – dieselbe Quelle wie-h,wikitool -hundtools/CONTRACT.md, aber eine eigene Darstellung (Entscheidung E5 in #185), kein Verweis auftools/CONTRACT.md. Sprache der Seiten: Englisch (AGENTS.md§ File naming, Punkt 3; die Datensätze sind ohnehin englisch).wikitool docs reference [--apply]intools/chemenu/commands/docs_verify.pynebendocs toc/docs prerequisites/docs contract, Pfad"docs reference"incli_contract.GROUPSunter „Types, instructions and docs" direkt nach"docs contract". Ohne--applyTrockenlauf (listet die Dateien, die sich ändern würden), mit--applyschreiben; idempotent. EigenerCommandRecordmit Zusammenfassung, Synopsis, Eigenschaften (WRITE, idempotent,COUNTED), Notes, Failure, Beispielen,never,see_also.tools/chemenu/reference_doc.py(nebeninstall_doc.py; Abweichung vom Entwurf „neue Funktion incli_contract.py"): es brauchttoc.anchorfür die Linkanker, undcli_contractsoll nichts auschemenuimportieren.cli_contractbekam nurexit_status_entries(rec)(die(code, Ursache)-Paare, aus denenrender_exit_status_linesjetzt formatiert).reference_doc.regions()ist die Liste vonRegion(path, name, render), diedocs referenceund der Stale-Check gemeinsam durchlaufen. #189 hängt dort zwei Einträge an.docs/reference/commands/<slug>.md, eine je Eintrag incli_contract.GROUPS.<slug>=reference_doc.group_slug: Gruppenname klein, jede Folge von Nicht-Alphanumerischem →-, Ränder getrimmt.# <Gruppenname>, ein handgeschriebener Kopfsatz, die Region<!-- wikitool:reference-commands -->…<!-- /wikitool:reference-commands -->. Keingroup="…"-Attribut im Marker:blocks._NAMEerlaubt nur[a-z][a-z0-9-]*, und die Gruppe folgt aus dem Dateinamen.docs/reference/commands/README.md: Kopf von Hand, Regionreference-commands-index– je Gruppe## <Gruppe>, „Full records: [.md](.md)" und eine Liste- [](<slug>.md#<anker>) - <summary>; Anker übertoc.anchor(neu, öffentlich), also wie im TOC.docs/reference/exit-codes.md: Kopf von Hand, Regionreference-exit-codes(Punkt 5).docs reference --applylegt keine Seite und keinen Marker an, wiedocs prerequisites: eine fehlende Seite oder ein fehlendes Markerpaar ist Exit 1 mit Dateipfad und Marker, und es wird dann gar nichts geschrieben.reference_doc.render_command):##`` (##, nicht###– die Seite hat#als Titel, das TOC soll eine Zeile je Kommando haben),summary, dann fette Labels Synopsis, Options (```text-Block; entfällt ohne Optionen), Examples (```bash), Behaviour (=notes), Properties, Exit codes (exit_status_entries, inkl. Code-0-Einträge und generischer 42-Zeile), See also.cli.options_texts(paths)(neu): baut den Kontext je Kommando vom Root aus mitmake_context(..., resilient_parsing=True)und ruftcli.render_options_text(vorher_render_options_text) – byte-gleich mit dem OPTIONS-Abschnitt von-h, per Test belegt.Changes files,Idempotent,Atomic,Counts toward the session call budget: yes|no|only when called with arguments,Can reach the network, und bei GatesGates: … - see [exit codes and gates](../exit-codes.md).Failure.reaction(nurcausebleibt) undnever. Für die Agenten bleibttools/CONTRACT.mdvollständig.exit-codes.md: ein fester Absatz, derAGENTS.md§ Tool error contract und § Gates verlinkt, nicht kopiert; darunter „Gates by command" (je verschiedenemProperties.gates-String, wörtlich, die deklarierenden Kommandos mit Link) und „Exit 42 causes" (je Kommando jede Ursache mit Code 42).toc.target_files().reference_doc.refreshwendet nach der Regiontoc.upsertan. Beim Bauen gefunden und behoben:toc.upsertsetzte das TOC vor die erste##-Überschrift – auf diesen Seiten lag die innerhalb der generierten Region, das TOC wäre in die Region geraten und beim nächsten Lauf überschrieben worden.toc._first_level2_offsetweicht jetzt auf den öffnenden Marker aus, wenn die erste##in einer anderen<!-- wikitool:… -->-Region liegt (auf dem code-maskierten Text, damit Marker in Inline-Code nicht zählen). Keine bestehende Datei hat sich dadurch geändert.check_reference_regionsindocs verify(vorcheck_toc_regions): Regionsinhalt gegen das Generat (das TOC prüft weitercheck_toc_regions, keine Doppelmeldung); fehlende Seite, fehlendes Markerpaar und eine Seite unterdocs/reference/commands/ohne Gruppe (außerREADME.md) sind Fehler mit Abhilfe. Ohnedocs/grün.docs verify-Datensatz: Note, zwei Failures,never,see_also, Erfolgszeile.check_readmes_have_no_command_table: keine Codeänderung; der Docstring voncommand_table_free_readmes()sagt, warumdocs/reference/commands/README.mdnicht dazugehört (geprüfte Kopie).tools/CONTRACT.md(Einleitung: drei Ansichten für Agenten, eine vierte für Menschen), Modul-Docstringcli_contract.py,tools/README.md§ Adding a command (Schritt 3),instructions/dev/doc-pull-through.md(Zeile zum Kommandoverhalten),docs/reference/README.md(verlinkt Kommandoreferenz und Exit-Codes; Seitentypen bleiben bis #189 beitypes describe),README.md§ Documentation,docs contract-Datensatz (see_also).stack-close): Der Modulbaum intools/README.mdnanntereference_doc.pynicht, und die Zeile zucli_contract.pyzählte nur drei Ansichten. Beides ist in 9.0.0-beta.4 nachgezogen. Geprüft und ohne Änderung geblieben:docs/explanation/language-boundaries.md, das die Kommandoreferenz schon als auscli_contractgeneriert beschreibt;README.md§ Maintenance, das den Wartungsplan intools/CONTRACT.mdmeint; die Routing-Zeile inAGENTS.md, dietools/CONTRACT.mdals Agentenreferenz nennt. Keine Installationsinstruktion war berührt.Version
MINOR – neuer Befehl, neuer Check, neue Dateien; drop-in in beide Richtungen. Gebumpt mit
version bump --minor --impact mediumauf9.0.0-beta.3(der Kandidat stand schon auf MAJOR, nur der Zähler stieg), der Nachzieh-Bump aus Punkt 10 mit--patch --impact lowauf9.0.0-beta.4.CHANGES.md: Bump-Zeilen und Themenabschnitt „Kommandoreferenz für Menschen unterdocs/reference/(#188)".Akzeptanzkriterien
cli_contract.GROUPSexistiert genau einedocs/reference/commands/<slug>.md, und jede registrierte Kommandopfad-Zeichenkette erscheint genau einmal als##`` in genau einer davon (test_every_group_has_one_page_and_every_command_one_section).Failure.reactionoder einennever-Text (test_no_page_carries_an_agent_addressed_field, echter Baum;test_a_generated_page_leaves_out_reactions_and_never, Fixture).docs reference --applyzweimal hintereinander: der zweite Lauf ändert nichts; nach dem ersten meldetdocs verifyweder eine veraltete Referenzregion noch ein veraltetes TOC (test_apply_twice_changes_nothing_the_second_time,test_a_long_page_gets_its_toc_outside_the_generated_region).--applylässtdocs verifymit einer Meldung scheitern, die die Datei unddocs reference --applynennt (test_a_changed_record_makes_verify_name_the_page_and_the_command).--applybyte-gleich (test_the_head_survives_apply_byte_for_byte).docs verifyscheitern;docs reference --applylegt in beiden Fällen nichts an und endet bei fehlender Seite mit Exit 1, das die Datei nennt (test_a_group_without_a_page_fails_and_nothing_is_created,test_a_page_without_a_group_fails,test_a_page_without_its_marker_pair_fails_and_is_left_alone).docs/besteht den neuen Check (test_a_tree_without_docs_passes).exit-codes.mdnennt jeden String, den ein Datensatz inProperties.gatesdeklariert, verlinktAGENTS.md#tool-error-contractundAGENTS.md#gatesund enthält keinen Satz aus diesen beiden Abschnitten (test_exit_codes_names_every_gate_and_links_rather_than_repeats_agents_md).test_a_long_page_gets_its_toc_outside_the_generated_region).dist export) sind die Seiten unverändert gegenüber dem Ursprungs-Repo (test_the_reference_pages_survive_dist_export_unchanged), unddocs verifyist im Zielbaum grün (CI-Schritt „The distribution works as a fresh instance" in den Läufen 580 und 582).pytest,docs verify,instructions verifylokal grün; CI-Läufe 580 und 582 und Release-Läufe 581 und 583 grün.Tests:
tools/chemenu/tests/test_reference_doc.py(19 Tests – echter Baum und Fixture-Baum).Nicht in diesem Paket
AGENTS.md§ Gates nennt fünf Gates (darunter das Iteration Budget, das mit 1 statt 42 endet), die Datensätze deklarieren sechs Namen (rebase-review,human-intervention-requiredstehen nicht in § Gates,instructions/gates.mdnenntrebase-reviewaber). Diese Abweichung bestand schon vor diesem Paket; die generierte Seite zeigt nur, was die Datensätze sagen. Weiterverfolgt in #194.Changelog: Gegen den Baum
01c888dgeprüft.status/blockedentfernt, weil #187 geschlossen ist. Korrigiert: Marker ohnegroup=-Attribut (blocks._NAMEerlaubt keins), Kommandos als##statt###, Abschnitt „Tools Integration“ →README.md§ Documentation, und Punkt 7 (check_readmes_have_no_command_table) braucht keine Codeänderung, nur einen Kommentar. Neu:--applylegt keine Seiten an (wiedocs prerequisites); TOC-Zusammenspiel (toc.upsertim selben Lauf); ohnedocs/grün; Wortlaut für die Eigenschaften (jetzt auchatomicundnetwork); Optionen über eine öffentliche Fassung voncli._render_options_text; Eintragsliste als Erweiterungspunkt für #189; Version auf den laufenden 9.0.0-Kandidaten bezogen. Die vorhandene Abweichung zwischen der Gate-Liste inAGENTS.mdund den Datensätzen ist ausdrücklich nicht Teil dieses Pakets.Changelog: Gebaut und publiziert als
9.0.0-beta.3in53383e7; CI-Lauf 580 und Release-Lauf 581 grün. Alle Akzeptanzkriterien abgehakt, jeweils mit dem Test, der sie belegt. Abweichungen vom Entwurf, im Body eingetragen: Das Rendering liegt in einem neuen Modulreference_doc.pystatt incli_contract.py. Hinzugekommen ist eine Korrektur intoc.py: Das TOC landet nie mehr in einer anderen generierten Region, auch das ist ein neues Kriterium mit Test. Der Stale-Check vergleicht nur den Regionsinhalt; das TOC prüft weiterhincheck_toc_regions. Neu sind außerdemcli.options_textsundtoc.anchor.Changelog: Body in den Endzustand gebracht. Neu ist Punkt 10 (Abschlussprüfung): Der Modulbaum in
tools/README.mdist nachgezogen, als 9.0.0-beta.4 ind644a1d; CI-Lauf 582 und Release-Lauf 583 sind grün. Die übrigen geprüften Dokumente sind benannt und blieben unverändert. Damit geschlossen.