instructions verify gleicht "wikitool commands used" gegen den Skill-Body ab #83

New Issue

2026-09-09T15:03:45Z

torben commented

2026-09-09 15:03:45 +00:00

Herkunft

Offene Frage aus #78, dort mit ja beantwortet und hierher ausgelagert. #78 fand die Drift per Wegwerf-Skript ueber alle fuenf SKILL.md: cite add fehlte in zwei Listen, types describe und xref add in je einer, publish in zweien; umgekehrt standen rm, log status, lint --markdown und lint --json in Listen, ohne dass ein Schritt sie begruendet. Behoben in 4.8.0-beta.11 — von Hand, und damit genau so lange richtig, bis der naechste Schritt sich aendert.

Befund

Der Abgleich ist rein mechanisch: Kommandovorkommen im Body gegen den Abschnitt "wikitool commands used", in beide Richtungen. Er ist zugleich die Art Drift, die beim Lesen niemand bemerkt — die Liste steht am Dateiende, der Schritt in der Mitte, und keine der beiden Stellen zeigt auf die andere. tools/wikitool instructions verify prueft heute Frontmatter, Referenzen, die dev/-Grenze und Byte-Gleichheit der publizierten Kopien; dieser Abgleich waere die naechste Regel derselben Art.

Was ihn nicht trivial macht

Drei Ausnahmeklassen, die ein Pruefer alle kennen muss, sonst meldet er dieselben Stellen bei jedem Lauf:

Delegation ueber publish-cycle.md. publish, log append, index rebuild und sources rebuild-index stehen in mehreren Listen, ohne dass ein Schritt sie aufruft — der Schritt sagt "Close out. publish-cycle.md". Das ist Absicht.
Benannte Delegation an eine andere Instruction. xref remove in wiki-manage gehoert zum Unlinking-Fall, den der Skill als Ganzes an page-lifecycle.md abgibt. Seit 4.8.0-beta.11 steht das als Satz unter der Liste.
Bewusste Abwesenheit. wiki-lint traegt seit 4.8.0-beta.11 einen Absatz **Deliberately absent:** mit rm und log status samt Grund. Ohne diesen Marker traegt sie jemand aus Vollstaendigkeit wieder ein — mit ihm meldet ein naiver Parser sie als "gelistet, aber unbenutzt".

Klasse 3 ist die einzige, die schon einen maschinenlesbaren Anker hat. Fuer 1 und 2 ist zu entscheiden, ob eine Allowlist im Code reicht (kurz, aber eine zweite Stelle, die mitgepflegt werden will) oder ob der Body die Delegation selbst markieren soll.

Zu entscheiden

Anker fuer Klasse 1 und 2: Allowlist in instructions_cmd.py, oder eine Markierung im Body?
Erfasst der Parser nur ## Steps und ## Decision points, oder den ganzen Body ausser dem Listenabschnitt? (Der wiki-lint-Trigger nennt log status, ohne es zu rufen — je nach Antwort ist das ein Treffer oder nicht.)
Zaehlt ein Kommando mit Flag (lint --markdown) als eigener Eintrag oder als lint?
Findung oder harter Fehler? Vorschlag: Findung — die Liste ist Doku, kein Ausfuehrungspfad.

Akzeptanzkriterien

tools/wikitool instructions verify meldet je Skill, welches Kommando ein Schritt oder Decision Point aufruft, ohne in der Liste zu stehen, und umgekehrt.
Die drei Ausnahmeklassen oben erzeugen keine Findung.
Der Stand nach 4.8.0-beta.11 laeuft ohne Findung durch — das ist der Regressionstest.
Tests in tools/chemenu/tests/test_instructions_cmd.py, inklusive je eines Falls pro Ausnahmeklasse.
tools/CONTRACT.md beschreibt die neue Findung; instructions/CONTRACT.md sagt, dass die Liste vollstaendig sein muss.

Betroffene Dateien

tools/chemenu/commands/instructions_cmd.py, tools/chemenu/tests/test_instructions_cmd.py, tools/CONTRACT.md, instructions/CONTRACT.md.

## Herkunft Offene Frage aus #78, dort mit **ja** beantwortet und hierher ausgelagert. #78 fand die Drift per Wegwerf-Skript ueber alle fuenf `SKILL.md`: `cite add` fehlte in zwei Listen, `types describe` und `xref add` in je einer, `publish` in zweien; umgekehrt standen `rm`, `log status`, `lint --markdown` und `lint --json` in Listen, ohne dass ein Schritt sie begruendet. Behoben in `4.8.0-beta.11` — von Hand, und damit genau so lange richtig, bis der naechste Schritt sich aendert. ## Befund Der Abgleich ist rein mechanisch: Kommandovorkommen im Body gegen den Abschnitt "wikitool commands used", in beide Richtungen. Er ist zugleich die Art Drift, die beim Lesen niemand bemerkt — die Liste steht am Dateiende, der Schritt in der Mitte, und keine der beiden Stellen zeigt auf die andere. `tools/wikitool instructions verify` prueft heute Frontmatter, Referenzen, die `dev/`-Grenze und Byte-Gleichheit der publizierten Kopien; dieser Abgleich waere die naechste Regel derselben Art. ## Was ihn nicht trivial macht Drei Ausnahmeklassen, die ein Pruefer alle kennen muss, sonst meldet er dieselben Stellen bei jedem Lauf: 1. **Delegation ueber `publish-cycle.md`.** `publish`, `log append`, `index rebuild` und `sources rebuild-index` stehen in mehreren Listen, ohne dass ein Schritt sie aufruft — der Schritt sagt "Close out. publish-cycle.md". Das ist Absicht. 2. **Benannte Delegation an eine andere Instruction.** `xref remove` in `wiki-manage` gehoert zum Unlinking-Fall, den der Skill als Ganzes an `page-lifecycle.md` abgibt. Seit `4.8.0-beta.11` steht das als Satz unter der Liste. 3. **Bewusste Abwesenheit.** `wiki-lint` traegt seit `4.8.0-beta.11` einen Absatz `**Deliberately absent:**` mit `rm` und `log status` samt Grund. Ohne diesen Marker traegt sie jemand aus Vollstaendigkeit wieder ein — mit ihm meldet ein naiver Parser sie als "gelistet, aber unbenutzt". Klasse 3 ist die einzige, die schon einen maschinenlesbaren Anker hat. Fuer 1 und 2 ist zu entscheiden, ob eine Allowlist im Code reicht (kurz, aber eine zweite Stelle, die mitgepflegt werden will) oder ob der Body die Delegation selbst markieren soll. ## Zu entscheiden - [ ] Anker fuer Klasse 1 und 2: Allowlist in `instructions_cmd.py`, oder eine Markierung im Body? - [ ] Erfasst der Parser nur `## Steps` und `## Decision points`, oder den ganzen Body ausser dem Listenabschnitt? (Der `wiki-lint`-Trigger nennt `log status`, ohne es zu rufen — je nach Antwort ist das ein Treffer oder nicht.) - [ ] Zaehlt ein Kommando mit Flag (`lint --markdown`) als eigener Eintrag oder als `lint`? - [ ] Findung oder harter Fehler? Vorschlag: Findung — die Liste ist Doku, kein Ausfuehrungspfad. ## Akzeptanzkriterien - [ ] `tools/wikitool instructions verify` meldet je Skill, welches Kommando ein Schritt oder Decision Point aufruft, ohne in der Liste zu stehen, und umgekehrt. - [ ] Die drei Ausnahmeklassen oben erzeugen keine Findung. - [ ] Der Stand nach `4.8.0-beta.11` laeuft ohne Findung durch — das ist der Regressionstest. - [ ] Tests in `tools/chemenu/tests/test_instructions_cmd.py`, inklusive je eines Falls pro Ausnahmeklasse. - [ ] `tools/CONTRACT.md` beschreibt die neue Findung; `instructions/CONTRACT.md` sagt, dass die Liste vollstaendig sein muss. ## Betroffene Dateien `tools/chemenu/commands/instructions_cmd.py`, `tools/chemenu/tests/test_instructions_cmd.py`, `tools/CONTRACT.md`, `instructions/CONTRACT.md`.