tools/CONTRACT.md: Nachschlage-Dokument statt Vollread - Kontextkosten senken #92

New Issue

2026-09-11T10:47:26Z

torben commented

2026-09-11 10:47:26 +00:00

Befund

tools/CONTRACT.md war mit 70.005 Bytes / 286 Zeilen / ~17.500 Tokens das mit Abstand größte Dokument im Repo - größer als AGENTS.md + kb/CONTRACT.md + raw/CONTRACT.md zusammen (50 KB). dist export liefert es an jede Instanz aus. 89 % lagen in den zwei Kommandotabellen (§ Commands 41.815 B, § Error contracts 20.352 B; alle acht übrigen Abschnitte zusammen 7.838 B).

Die Datei war für gezielten Abruf bereits hervorragend gebaut und wurde trotzdem als Ganzes gelesen: eine Zeile = ein Kommando = physisch einzeilig, also liefert grep -n '^| `raw accept' genau beide Zeilen dieses Kommandos und nichts sonst. Nur stand das nirgends - AGENTS.md Z186 routete mit "Full command reference", was sich als Vollread-Aufforderung liest.

Zweitbefund: keine Anker unterhalb ##. Im ganzen Repo existierte genau ein Anker-Link in die Datei (README.md:308 → #maintenance-schedule); die übrigen 19 Verweise zeigten auf die Datei als Ganzes.

Drittbefund: die beiden Tabellen standen in unterschiedlicher Reihenfolge (links show einmal zwischen xref link-source und cite id, einmal zwischen version release und migrate list; sources coverage/trace, budget und eval ebenso), sodass die zwei Hälften eines Vertrags nicht parallel lesbar waren.

Akzeptanzkriterien

Lead-in-Regel vor dem TOC, die das Nachschlagen einer Zeile zur normalen Zugriffsart erklärt und die konkrete grep-Zeile nennt - genau einmal (Invariante 8).
AGENTS.mds Routing-Zelle für tools/ beschreibt jetzt die Form ("one row per command in each of two tables - a file to look a row up in rather than read through, as its own opening paragraph says") statt "Full command reference", ohne die grep-Zeile zu wiederholen.
Beide Tabellen in vierzehn ###-Untergruppen gegliedert, jede mit eigenem Tabellenkopf. docs toc --apply erzeugt daraus erstmals Anker unterhalb ## (dedupliziert als #pages / #pages-1).
§ Error contracts steht in derselben Gruppen- und Zeilenreihenfolge wie § Commands. Mechanisch abgesichert: das Umstellungsskript behauptet die Multimenge der Erst-Zellen vor und nach dem Schreiben und bricht sonst ab - 60 § Commands-Zeilen, 57 § Error-contracts-Zeilen (56 Kommandos + die *(any command)*-Zeile) unverändert.
### bricht docs_verify.section_text() nicht - Lookahead (?=^#{1,2}[ \t]|\Z) verlangt nach 1-2 # ein Space/Tab. Zwei neue Tests: test_a_section_runs_on_past_its_own_subheadings und test_grouped_tables_are_still_checked_in_both_directions.
TOC per tools/wikitool docs toc --apply erzeugt, nicht von Hand.
pytest (1195 passed), docs verify, instructions verify grün.
5.0.0-beta.13 → 5.0.0-beta.14 (--patch, max-wins gegen den bereits MAJOR-eskalierten Kandidaten), Changelog-Prosa geschrieben.

Beim Umsetzen zusätzlich gefunden und behoben

Die dist export-Zeile in § Commands war über vier physische Zeilen umgebrochen und damit kein gültiger GFM-Tabellen-Datensatz mehr - sie renderte gebrochen. docs verify hatte das nicht gesehen, weil TABLE_CELL_RE nur die erste Zeile braucht. Beim Umsortieren wurden die Fortsetzungszeilen zusammengeführt (1.860 Zeichen, jetzt eine Zeile).

Ergebnis

	vorher	nachher
Datei gesamt	70.005 B	74.589 B (+6,5 % für Überschriften, Tabellenköpfe, längeres TOC)
Kopf bis TOC-Ende (was ein Preview sieht)	~1.100 B	2.714 B (~680 tok) - enthält jetzt den vollen Gruppenindex
typischer Zugriff (ein Kommando)	17.500 tok (Vollread)	Median 229 tok, Mittel 278, Max 1.105 (`raw accept`)

Bewusst nicht umgesetzt

Die 17 Tabellenzellen über 900 Zeichen wurden nicht entzerrt. Der ursprüngliche Vorschlag war, ihren Begründungsanteil nach docs/ zu verschieben. Die Gegenprobe an der größten Zelle (publish, 3.375 Zeichen) hat den Vorschlag widerlegt: die Kandidaten dafür - "a third outcome distinct from success (0) and a validation error (1)", "so a clearance carries neither to a different file list nor to edited contents", "each is recomputable from the tree, so approving it decides nothing", "the way past it is the user adding the URL to that file, and an agent editing it to get past a refusal is opening a gate on its own initiative" - sind für eine handelnde Session normativ verwertbar, nicht Hintergrund. Die Zelle zu kürzen hätte die Handlungsfähigkeit gesenkt, und docs/ trägt laut AGENTS.md § File naming ohnehin keinen normativen Satz. Sobald der Zugriff zeilenweise erfolgt, ist die Zellenlänge außerdem kein Kontextproblem mehr: das teuerste Kommando kostet 1.105 statt 17.500 Tokens. Die Zellen sind lang, weil die Verträge dicht sind.

Die im Anlegen notierte offene Frage - ob "Read-only and exempt from the Iteration Budget Gate" über ~10 Zellen hinweg konsolidiert gehört - ist damit ebenfalls beantwortet und wird nicht weiterverfolgt: eine hochgezogene Gruppen-Präambel stünde nicht mehr in der Zeile, die ein grep liefert, und würde genau die Eigenschaft zerstören, die dieses Paket ausbaut.

Verifiziert

Commit 95ab408 auf main. tools/wikitool docs verify (55 Kommandos dokumentiert, TOCs auf 38 Referenzdateien aktuell), tools/wikitool instructions verify (22 Instructions, 7 Skills), volle pytest-Suite 1195 passed. Kein docs/-Rationale und keine Menschendoku wurde stale: alle 19 übrigen Verweise auf die Datei sind Wegweiser auf die Datei als Ganzes und bleiben korrekt, README.md:377 und instructions/dev/doc-pull-through.md:36 beschreiben weiterhin zutreffend, was drinsteht.

Modell-Handover

Analyse, Design, Versionsteil-Entscheidung und die Verwerfung des Punkts "Monsterzellen entzerren" auf Sonnet 5, Effort high. Mechanische Mitte (Umstellungsskript, Tests, Bump) und diese Schlussphase ebenfalls Sonnet 5 / high - die ganze Sitzung auf einem Modell, der Switch wurde an beiden Übergängen angeboten und nicht gezogen.

## Befund `tools/CONTRACT.md` war mit **70.005 Bytes / 286 Zeilen / ~17.500 Tokens** das mit Abstand größte Dokument im Repo - größer als `AGENTS.md` + `kb/CONTRACT.md` + `raw/CONTRACT.md` zusammen (50 KB). `dist export` liefert es an jede Instanz aus. 89 % lagen in den zwei Kommandotabellen (§ Commands 41.815 B, § Error contracts 20.352 B; alle acht übrigen Abschnitte zusammen 7.838 B). Die Datei war für gezielten Abruf bereits hervorragend gebaut und wurde trotzdem als Ganzes gelesen: eine Zeile = ein Kommando = physisch einzeilig, also liefert ``grep -n '^| `raw accept' `` genau beide Zeilen dieses Kommandos und nichts sonst. Nur stand das nirgends - `AGENTS.md` Z186 routete mit "Full command reference", was sich als Vollread-Aufforderung liest. Zweitbefund: keine Anker unterhalb `##`. Im ganzen Repo existierte genau *ein* Anker-Link in die Datei (`README.md:308` → `#maintenance-schedule`); die übrigen 19 Verweise zeigten auf die Datei als Ganzes. Drittbefund: die beiden Tabellen standen in unterschiedlicher Reihenfolge (`links show` einmal zwischen `xref link-source` und `cite id`, einmal zwischen `version release` und `migrate list`; `sources coverage`/`trace`, `budget` und `eval` ebenso), sodass die zwei Hälften eines Vertrags nicht parallel lesbar waren. ## Akzeptanzkriterien - [x] Lead-in-Regel vor dem TOC, die das Nachschlagen einer Zeile zur normalen Zugriffsart erklärt und die konkrete `grep`-Zeile nennt - genau einmal (Invariante 8). - [x] `AGENTS.md`s Routing-Zelle für `tools/` beschreibt jetzt die Form ("one row per command in each of two tables - a file to look a row up in rather than read through, as its own opening paragraph says") statt "Full command reference", ohne die `grep`-Zeile zu wiederholen. - [x] Beide Tabellen in **vierzehn** `###`-Untergruppen gegliedert, jede mit eigenem Tabellenkopf. `docs toc --apply` erzeugt daraus erstmals Anker unterhalb `##` (dedupliziert als `#pages` / `#pages-1`). - [x] § Error contracts steht in derselben Gruppen- und Zeilenreihenfolge wie § Commands. Mechanisch abgesichert: das Umstellungsskript behauptet die Multimenge der Erst-Zellen vor und nach dem Schreiben und bricht sonst ab - 60 § Commands-Zeilen, 57 § Error-contracts-Zeilen (56 Kommandos + die `*(any command)*`-Zeile) unverändert. - [x] `###` bricht `docs_verify.section_text()` nicht - Lookahead `(?=^#{1,2}[ \t]|\Z)` verlangt nach 1-2 `#` ein Space/Tab. Zwei neue Tests: `test_a_section_runs_on_past_its_own_subheadings` und `test_grouped_tables_are_still_checked_in_both_directions`. - [x] TOC per `tools/wikitool docs toc --apply` erzeugt, nicht von Hand. - [x] `pytest` (1195 passed), `docs verify`, `instructions verify` grün. - [x] `5.0.0-beta.13` → `5.0.0-beta.14` (`--patch`, max-wins gegen den bereits MAJOR-eskalierten Kandidaten), Changelog-Prosa geschrieben. ## Beim Umsetzen zusätzlich gefunden und behoben Die `dist export`-Zeile in § Commands war über **vier physische Zeilen umgebrochen** und damit kein gültiger GFM-Tabellen-Datensatz mehr - sie renderte gebrochen. `docs verify` hatte das nicht gesehen, weil `TABLE_CELL_RE` nur die erste Zeile braucht. Beim Umsortieren wurden die Fortsetzungszeilen zusammengeführt (1.860 Zeichen, jetzt eine Zeile). ## Ergebnis | | vorher | nachher | |---|---|---| | Datei gesamt | 70.005 B | 74.589 B (+6,5 % für Überschriften, Tabellenköpfe, längeres TOC) | | Kopf bis TOC-Ende (was ein Preview sieht) | ~1.100 B | 2.714 B (~680 tok) - enthält jetzt den vollen Gruppenindex | | **typischer Zugriff (ein Kommando)** | **17.500 tok (Vollread)** | **Median 229 tok**, Mittel 278, Max 1.105 (`raw accept`) | ## Bewusst nicht umgesetzt **Die 17 Tabellenzellen über 900 Zeichen wurden nicht entzerrt.** Der ursprüngliche Vorschlag war, ihren Begründungsanteil nach `docs/` zu verschieben. Die Gegenprobe an der größten Zelle (`publish`, 3.375 Zeichen) hat den Vorschlag widerlegt: die Kandidaten dafür - "a third outcome distinct from success (0) and a validation error (1)", "so a clearance carries neither to a different file list nor to edited contents", "each is recomputable from the tree, so approving it decides nothing", "the way past it is the user adding the URL to that file, and an agent editing it to get past a refusal is opening a gate on its own initiative" - sind für eine handelnde Session normativ verwertbar, nicht Hintergrund. Die Zelle zu kürzen hätte die Handlungsfähigkeit gesenkt, und `docs/` trägt laut `AGENTS.md` § File naming ohnehin keinen normativen Satz. Sobald der Zugriff zeilenweise erfolgt, ist die Zellenlänge außerdem kein Kontextproblem mehr: das teuerste Kommando kostet 1.105 statt 17.500 Tokens. Die Zellen sind lang, weil die Verträge dicht sind. Die im Anlegen notierte offene Frage - ob "Read-only and exempt from the Iteration Budget Gate" über ~10 Zellen hinweg konsolidiert gehört - ist damit ebenfalls beantwortet und wird **nicht** weiterverfolgt: eine hochgezogene Gruppen-Präambel stünde nicht mehr in der Zeile, die ein `grep` liefert, und würde genau die Eigenschaft zerstören, die dieses Paket ausbaut. ## Verifiziert Commit `95ab408` auf `main`. `tools/wikitool docs verify` (55 Kommandos dokumentiert, TOCs auf 38 Referenzdateien aktuell), `tools/wikitool instructions verify` (22 Instructions, 7 Skills), volle `pytest`-Suite 1195 passed. Kein `docs/`-Rationale und keine Menschendoku wurde stale: alle 19 übrigen Verweise auf die Datei sind Wegweiser auf die Datei als Ganzes und bleiben korrekt, `README.md:377` und `instructions/dev/doc-pull-through.md:36` beschreiben weiterhin zutreffend, was drinsteht. ## Modell-Handover Analyse, Design, Versionsteil-Entscheidung und die Verwerfung des Punkts "Monsterzellen entzerren" auf Sonnet 5, Effort `high`. Mechanische Mitte (Umstellungsskript, Tests, Bump) und diese Schlussphase ebenfalls Sonnet 5 / `high` - die ganze Sitzung auf einem Modell, der Switch wurde an beiden Übergängen angeboten und nicht gezogen.

torben added the prio/planned size/M area/process kind/build labels 2026-09-11 10:47:26 +00:00

torben referenced this issue from a commit

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

docs: tools/CONTRACT.md als Nachschlage-Dokument strukturiert, AGENTS.md-Routing angepasst (schliesst #92)

torben commented

2026-09-11 10:53:03 +00:00

Changelog: Alle acht Akzeptanzkriterien abgehakt und geschlossen (Commit 95ab408, 5.0.0-beta.14). Neu im Body: der gefundene GFM-Bruch in der dist export-Zeile, die Ergebnistabelle (Median 229 statt 17.500 Tokens pro Zugriff) und die Verifikation. Der Abschnitt „Bewusst nicht Teil dieses Pakets" ist zu „Bewusst nicht umgesetzt" geworden - die Gegenprobe an der publish-Zelle hat den Vorschlag widerlegt, statt ihn nur zu vertagen; die offene Frage zur Konsolidierung der „Read-only"-Wiederholung ist mit derselben Begründung verworfen und nicht als Folge-Issue abgelegt.

**Changelog:** Alle acht Akzeptanzkriterien abgehakt und geschlossen (Commit `95ab408`, `5.0.0-beta.14`). Neu im Body: der gefundene GFM-Bruch in der `dist export`-Zeile, die Ergebnistabelle (Median 229 statt 17.500 Tokens pro Zugriff) und die Verifikation. Der Abschnitt „Bewusst nicht Teil dieses Pakets" ist zu „Bewusst nicht umgesetzt" geworden - die Gegenprobe an der `publish`-Zelle hat den Vorschlag widerlegt, statt ihn nur zu vertagen; die offene Frage zur Konsolidierung der „Read-only"-Wiederholung ist mit derselben Begründung verworfen und nicht als Folge-Issue abgelegt.

torben closed this issue

2026-09-11 10:53:07 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: torben/chemenu#92