AGENTS.md sagt Contract-Prosa sei maschinell geprüft - und kein Skill zieht sie nach #90

New Issue

2026-09-11T09:33:50Z

torben commented

2026-09-11 09:33:50 +00:00

Befund (behoben)

AGENTS.md § Changelog wies die Contract-Prosa fälschlich der Maschine zu:

A stack change is not finished until the human docs describe it. README.md, EVALS.md and tools/README.md are part of the change that introduced a stage, a command or a workflow […] The mechanical half - command tables, contracts, ignore canaries - is checked by tools/wikitool docs verify; the prose half is yours.

Zwei Fehler in einem Satz:

Die Aufzählung war falsch. docs verify prüft von einer Contract-Zelle ausschließlich, dass der Kommandopfad irgendwo in einer Tabelle der Datei vorkommt. Der Zellentext selbst wurde nie gelesen - ein neues --flag an einem bestehenden Kommando war vollständig unsichtbar.
Die Sitzungspflicht war auf drei Dateien eingegrenzt (README.md, EVALS.md, tools/README.md). tools/CONTRACT.md und die <stage>/CONTRACT.md standen laut Satz 1 auf der geprüften Seite und damit auf keiner Liste, die jemand nachzieht.

Dazu die dritte Hälfte des Problems: kein Skill benannte den Doku-Nachzug überhaupt. stack-dev fragte an keinem Schritt, welche Dokumente etwas über die berührte Fläche behaupten; stack-close Schritt 3 deckte docs/, README.md/INSTALL.md/DEVELOPMENT.md und die Prosa einer neuen Instruction ab, aber keine Contracts.

Warum das zählt

Die Klasse „ein Dokument beschreibt einen Mechanismus, der sich geändert hat, und nichts hat es gemerkt" ist die größte Defektklasse im Tracker: #89 (raw accept-Prosa nach #67), #76 (session-setup.md § Scope nennt ein anderes Kriterium als die echte Budget-Ausnahmeliste), #70, #63, #29, #78/#83 (Skill-Kommandolisten gedriftet, von Hand behoben). #67s Akzeptanzkriterium war eng formuliert und wurde wahrheitsgemäß abgehakt, während die Nachbarzellen verrotteten. Modell-Toleranz ist der Auslöser; die falsche Zusicherung war der Grund, warum nichts bremste.

Entscheidung

Schnitt: nur die falsche Zusicherung aus AGENTS.md entfernen, keine neue detaillierte Aufzählung schreiben - die vollständige Aufzählung existiert bereits in tools/CONTRACT.mds docs verify-Zeile, und ihre Präzisierung ist #91s Aufgabe, nicht diese hier. Die Nachzugsliste selbst wandert in eine eigene Instruction (instructions/dev/doc-pull-through.md), nicht in AGENTS.md oder den Skill-Body - selektive Disclosure: „was genau prüft docs verify" ist kein Dauerwissen für jede Sitzung.

Akzeptanzkriterien

AGENTS.md § Changelog nennt die Aufzählung „command tables, contracts, ignore canaries" nicht mehr. Verweist stattdessen auf die docs verify-Zeile in tools/CONTRACT.md und macht jede Zellenprosa - Kommandotabelle, Fehlerkontrakt, Stage-Contracts - explizit zur Sitzungsarbeit.
Der Absatz grenzt die Sitzungspflicht nicht mehr auf README.md/EVALS.md/tools/README.md ein - tools/CONTRACT.md und der berührte <stage>/CONTRACT.md stehen jetzt ausdrücklich daneben.
check_cli_readme()s Docstring in tools/chemenu/commands/docs_verify.py behauptet nicht mehr, sie prüfe „tools/CONTRACT.md's command table" - sie beschreibt jetzt, dass TABLE_CELL_RE das ganze Dokument scannt und nur den gebacktickten Pfad liest, nie die restliche Zelle.
instructions/dev/doc-pull-through.md existiert, Frontmatter nach types/instruction.md, und listet je berührter Fläche das zuständige Dokument: beide tools/CONTRACT.md-Tabellen, der berührte <stage>/CONTRACT.md, AGENTS.md bei verschobener Regel/Gate/Invariante, die README-artigen Dateien, docs/ bei verschobener Begründung.
stack-dev hat einen neuen Schritt 5 zwischen Versionsbump und Verify/Publish (jetzt Schritt 6) - ein Satz plus Link; die Liste bleibt in der Instruction, der Skill-Body wuchs nur um diesen einen Schritt.
Die neue Instruction ist in stack-dev Schritt 2s Katalog gelistet.
stack-close Schritt 3 nennt die Contracts jetzt neben docs/ und den README-artigen Dateien.
tools/wikitool instructions verify, tools/wikitool docs verify und pytest in tools/ liefen grün (1185 passed); instructions sync hat die Skills neu publiziert.
Versionsbump per tools/wikitool version bump --minor: 5.0.0-beta.11 -> 5.0.0-beta.12. Drop-in in beide Richtungen; der Kandidat trug seine --breaking-Zeile bereits aus einem früheren Bump, diese Änderung fügte keine neue hinzu.

Nicht in diesem Paket

Jede Änderung an docs_verify.py außer der Docstring - das ist #91.
Der Nachtrag der 10 fehlenden Fehlerkontrakt-Zeilen - ebenfalls #91: ohne den dort neuen Check gibt es keine Regel, die sie verlangt.

Nebenbei gefunden und mitgezogen

Beim Nachziehen der stack-dev-Umnummerierung fielen zwei bereits vorher falsche Schrittverweise auf stack-dev auf, unabhängig von dieser Umnummerierung selbst entstanden: instructions/dev/version-parts.md verwies auf „Schritt 3" statt auf den Versionsbump-Schritt (jetzt korrekt „Schritt 4"), instructions/dev/testing-conventions.md verwies auf „Schritt 4" statt auf den Verify/Publish-Schritt (jetzt korrekt „Schritt 6"). Beide im selben Commit korrigiert.

Verifiziert

Commit 441a815 auf main (tools/wikitool publish). Vor dem Publish liefen tools/wikitool docs verify, tools/wikitool instructions verify (nach instructions sync) und die volle pytest-Suite in tools/ (1185 passed) grün.

## Befund (behoben) `AGENTS.md` § Changelog wies die Contract-Prosa fälschlich der Maschine zu: > **A stack change is not finished until the human docs describe it.** `README.md`, `EVALS.md` and `tools/README.md` are part of the change that introduced a stage, a command or a workflow […] The mechanical half - command tables, **contracts**, ignore canaries - is checked by `tools/wikitool docs verify`; the prose half is yours. Zwei Fehler in einem Satz: 1. **Die Aufzählung war falsch.** `docs verify` prüft von einer Contract-Zelle ausschließlich, dass der *Kommandopfad* irgendwo in einer Tabelle der Datei vorkommt. Der Zellentext selbst wurde nie gelesen - ein neues `--flag` an einem bestehenden Kommando war vollständig unsichtbar. 2. **Die Sitzungspflicht war auf drei Dateien eingegrenzt** (`README.md`, `EVALS.md`, `tools/README.md`). `tools/CONTRACT.md` und die `<stage>/CONTRACT.md` standen laut Satz 1 auf der geprüften Seite und damit auf keiner Liste, die jemand nachzieht. Dazu die dritte Hälfte des Problems: kein Skill benannte den Doku-Nachzug überhaupt. `stack-dev` fragte an keinem Schritt, welche Dokumente etwas über die berührte Fläche behaupten; `stack-close` Schritt 3 deckte `docs/`, `README.md`/`INSTALL.md`/`DEVELOPMENT.md` und die Prosa einer neuen Instruction ab, aber keine Contracts. ## Warum das zählt Die Klasse „ein Dokument beschreibt einen Mechanismus, der sich geändert hat, und nichts hat es gemerkt" ist die größte Defektklasse im Tracker: #89 (`raw accept`-Prosa nach #67), #76 (`session-setup.md` § Scope nennt ein anderes Kriterium als die echte Budget-Ausnahmeliste), #70, #63, #29, #78/#83 (Skill-Kommandolisten gedriftet, von Hand behoben). #67s Akzeptanzkriterium war eng formuliert und wurde wahrheitsgemäß abgehakt, während die Nachbarzellen verrotteten. Modell-Toleranz ist der Auslöser; die falsche Zusicherung war der Grund, warum nichts bremste. ## Entscheidung Schnitt: nur die falsche Zusicherung aus `AGENTS.md` entfernen, keine neue detaillierte Aufzählung schreiben - die vollständige Aufzählung existiert bereits in `tools/CONTRACT.md`s `docs verify`-Zeile, und ihre Präzisierung ist #91s Aufgabe, nicht diese hier. Die Nachzugsliste selbst wandert in eine eigene Instruction (`instructions/dev/doc-pull-through.md`), nicht in `AGENTS.md` oder den Skill-Body - selektive Disclosure: „was genau prüft `docs verify`" ist kein Dauerwissen für jede Sitzung. ## Akzeptanzkriterien - [x] `AGENTS.md` § Changelog nennt die Aufzählung „command tables, contracts, ignore canaries" nicht mehr. Verweist stattdessen auf die `docs verify`-Zeile in `tools/CONTRACT.md` und macht jede Zellenprosa - Kommandotabelle, Fehlerkontrakt, Stage-Contracts - explizit zur Sitzungsarbeit. - [x] Der Absatz grenzt die Sitzungspflicht nicht mehr auf `README.md`/`EVALS.md`/`tools/README.md` ein - `tools/CONTRACT.md` und der berührte `<stage>/CONTRACT.md` stehen jetzt ausdrücklich daneben. - [x] `check_cli_readme()`s Docstring in `tools/chemenu/commands/docs_verify.py` behauptet nicht mehr, sie prüfe „tools/CONTRACT.md's command table" - sie beschreibt jetzt, dass `TABLE_CELL_RE` das ganze Dokument scannt und nur den gebacktickten Pfad liest, nie die restliche Zelle. - [x] `instructions/dev/doc-pull-through.md` existiert, Frontmatter nach `types/instruction.md`, und listet je berührter Fläche das zuständige Dokument: beide `tools/CONTRACT.md`-Tabellen, der berührte `<stage>/CONTRACT.md`, `AGENTS.md` bei verschobener Regel/Gate/Invariante, die README-artigen Dateien, `docs/` bei verschobener Begründung. - [x] `stack-dev` hat einen neuen Schritt 5 zwischen Versionsbump und Verify/Publish (jetzt Schritt 6) - ein Satz plus Link; die Liste bleibt in der Instruction, der Skill-Body wuchs nur um diesen einen Schritt. - [x] Die neue Instruction ist in `stack-dev` Schritt 2s Katalog gelistet. - [x] `stack-close` Schritt 3 nennt die Contracts jetzt neben `docs/` und den README-artigen Dateien. - [x] `tools/wikitool instructions verify`, `tools/wikitool docs verify` und `pytest` in `tools/` liefen grün (1185 passed); `instructions sync` hat die Skills neu publiziert. - [x] Versionsbump per `tools/wikitool version bump --minor`: 5.0.0-beta.11 -> 5.0.0-beta.12. Drop-in in beide Richtungen; der Kandidat trug seine `--breaking`-Zeile bereits aus einem früheren Bump, diese Änderung fügte keine neue hinzu. ## Nicht in diesem Paket - Jede Änderung an `docs_verify.py` außer der Docstring - das ist #91. - Der Nachtrag der 10 fehlenden Fehlerkontrakt-Zeilen - ebenfalls #91: ohne den dort neuen Check gibt es keine Regel, die sie verlangt. ## Nebenbei gefunden und mitgezogen Beim Nachziehen der `stack-dev`-Umnummerierung fielen zwei bereits vorher falsche Schrittverweise auf `stack-dev` auf, unabhängig von dieser Umnummerierung selbst entstanden: `instructions/dev/version-parts.md` verwies auf „Schritt 3" statt auf den Versionsbump-Schritt (jetzt korrekt „Schritt 4"), `instructions/dev/testing-conventions.md` verwies auf „Schritt 4" statt auf den Verify/Publish-Schritt (jetzt korrekt „Schritt 6"). Beide im selben Commit korrigiert. ## Verifiziert Commit `441a815` auf `main` (`tools/wikitool publish`). Vor dem Publish liefen `tools/wikitool docs verify`, `tools/wikitool instructions verify` (nach `instructions sync`) und die volle `pytest`-Suite in `tools/` (1185 passed) grün.

torben added the prio/blocking size/S area/process kind/defect labels 2026-09-11 09:33:50 +00:00

~~torben referenced this issue 2026-09-11 09:34:27 +00:00~~

docs verify prüft die beiden Tabellen in tools/CONTRACT.md nicht getrennt - Fehlerkontrakt gar nicht #91

torben referenced this issue from a commit

2026-09-11 09:59:44 +00:00

fix(docs): AGENTS.md-Contract-Prosa als Sitzungsarbeit klargestellt, doc-pull-through-Instruction (schliesst #90)

torben closed this issue

2026-09-11 10:00:52 +00:00

torben commented

2026-09-11 10:00:55 +00:00

Changelog: AGENTS.md § Changelog korrigiert (Contract-Prosa als Sitzungsarbeit benannt statt fälschlich als maschinell geprüft aufgezählt, Sitzungspflicht auf tools/CONTRACT.md/<stage>/CONTRACT.md erweitert). check_cli_readme()-Docstring korrigiert. Neue Instruction instructions/dev/doc-pull-through.md. stack-dev bekommt neuen Schritt 5 (Verify/Publish rückt auf Schritt 6), Katalog in Schritt 2 erweitert. stack-close Schritt 3 nennt jetzt die Contracts. Nebenbei zwei vorbestehende falsche Schrittverweise in version-parts.md/testing-conventions.md korrigiert. Versionsbump --minor (5.0.0-beta.11 -> 5.0.0-beta.12). Commit 441a815.

**Changelog:** `AGENTS.md` § Changelog korrigiert (Contract-Prosa als Sitzungsarbeit benannt statt fälschlich als maschinell geprüft aufgezählt, Sitzungspflicht auf `tools/CONTRACT.md`/`<stage>/CONTRACT.md` erweitert). `check_cli_readme()`-Docstring korrigiert. Neue Instruction `instructions/dev/doc-pull-through.md`. `stack-dev` bekommt neuen Schritt 5 (Verify/Publish rückt auf Schritt 6), Katalog in Schritt 2 erweitert. `stack-close` Schritt 3 nennt jetzt die Contracts. Nebenbei zwei vorbestehende falsche Schrittverweise in `version-parts.md`/`testing-conventions.md` korrigiert. Versionsbump `--minor` (5.0.0-beta.11 -> 5.0.0-beta.12). Commit `441a815`.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: torben/chemenu#90