kb/CONVENTIONS.md.template traegt keine TOC-Region: frische Instanz und CI scheitern an docs verify #106

New Issue

2026-09-15T20:28:19Z

torben commented

2026-09-15 20:28:19 +00:00

Befund (behoben in `6.0.1`)

kb/CONVENTIONS.md.template war 105 Zeilen lang und trug keine -Region.
Die TOC-Pflicht gilt fuer jede Referenzdatei ueber 100 Zeilen (tools/chemenu/toc.py,
THRESHOLD = 100), und kb/CONVENTIONS.md steht in toc.target_files(). Eine Instanz, die das
Template nach instructions/setup-instance.md adoptierte, bekam damit eine kb/CONVENTIONS.md
ohne Region - und fiel am tools/wikitool docs verify in Schritt 13 derselben Anleitung
(instructions/setup-instance.md:264) um:

ERROR Documentation issues found:
- kb/CONVENTIONS.md needs a table-of-contents region refreshed - run `wikitool docs toc --apply`

Das war kein CI-Artefakt: der dokumentierte Installationsweg einer frisch ausgelieferten Instanz
endete in einem roten docs verify. Ausgeliefert war der Defekt in 6.0.0, behoben in 6.0.1.

Ursache

toc.target_files() berechnete den Dateisatz ueber die adoptierten Namen -
kb/CONVENTIONS.md, kb/*/COLLECTION.md, instructions/**.md, types/*.md, docs/*.md. Eine
.template-Datei endet auf .md.template und fiel damit aus jedem dieser Walks heraus:
docs toc --apply hat das Template nie angefasst, docs verify es nie gelesen. Geprueft wurde
erst die adoptierte Kopie, die es im Ursprungs-Repo gar nicht gibt.

Solange das Template unter 100 Zeilen blieb, war das folgenlos. f350999 (2026-09-15,
"Control-Plane-Sprache universell") hat es von 99 auf 105 Zeilen wachsen lassen - genau ueber die
Schwelle:

Commit	Zeilen	CI
`c64479f`	99	gruen (Run 274)
`f350999`	105	rot (Run 279)

Seither war ci.yml auf jedem Push rot (Runs 279, 281, 282, 284, 285, 287, 289). Dass es wie
Flackern aussah, lag an der Paarung: jeder Push erzeugt zusaetzlich einen release.yml-Lauf, und
der ist gruen. Die gruen/rot-Paare pro Commit sind zwei verschiedene Workflows, keine
Wiederholungslaeufe - diese Fehllesung hat den roten Zustand fuenf Pushes lang ueberlebt.

Entscheidung und Umsetzung

Umgesetzt wie vorgeschlagen: eine in Scope stehende Datei nimmt ihr <name>.template mit
hinein, wenn eines existiert (toc.target_files()). Das Template ist dasselbe Dokument einen
Schritt frueher in seinem Leben; wer es auslaesst, laesst die adoptierte Kopie den Fehler erben.
Der Scope bleibt berechnet statt handgepflegt, also sind types/*.md.template und
kb/*/COLLECTION.md.template automatisch mit abgedeckt, sobald eines ueber die Schwelle waechst.

Verworfen, wie im urspruenglichen Vorschlag:

Template unter 100 Zeilen kuerzen - haelt bis zum naechsten Absatz.
docs toc --apply im CI-Replay nach der Adoption - repariert den Testpfad und laesst den
echten Nutzerpfad kaputt.

Die offene Frage ist beantwortet: die Platzhalter des Templates ({language}) kollidieren nicht -
die Ueberschriften sind Klartext, docs toc --apply erzeugt eine korrekte Region.

Grenzuebertritt geprueft und verneint. Das Template ist stack-eigen
(ownership.is_stack_owned: jede .template unter einer Content-Stage), steht nicht in
UPGRADE_PRESERVED_PATHS, und dist upgrade schreibt es damit mit - eine Instanz bekommt das
reparierte Template durch den Upgrade selbst, ohne Handarbeit. Der Rueckweg funktioniert ebenso,
weil die alte Maschinerie das Template gar nicht prueft. Handarbeit faellt nur an, wo eine Instanz
ihr stack-eigenes Template lokal veraendert hat; dist upgrade meldet genau das als blocked und
verlangt --keep-local. Daher --patch, kein --breaking.

Nebenbei aufgeraeumt: docs_verify.TEMPLATE_SUFFIX war eine zweite Schreibung derselben Konstante
und kommt jetzt aus toc (kein Zyklus - docs_verify importiert toc ohnehin). ownership.py
behaelt seine eigene bewusst: andere Frage, engerer Scope.

Akzeptanzkriterien

Nach dist export + Adoption der Templates laeuft tools/wikitool docs verify in der
frischen Instanz ohne Befund durch. Verifiziert per vollstaendigem
setup-instance.md-Replay gegen einen frischen Export: doctor, docs verify
(59 Referenzdateien), instructions verify und lint --fail-on-error gruen.
docs toc --apply haelt kb/CONVENTIONS.md.template im Ursprungs-Repo aktuell; die Region
ist vom Werkzeug geschrieben, nicht von Hand. docs verify prueft dort jetzt 57 statt 56
Referenzdateien.
Test deckt den Fall ab:
test_a_shipped_template_over_the_threshold_without_a_region_is_reported - ein .template
ueber der Schwelle ohne Region ist ein Befund. Dazu
test_target_files_takes_the_shipped_template_of_a_file_in_scope und
test_target_files_takes_a_template_only_for_a_file_already_in_scope (ein USER.md.template
ohne Referenzdatei daneben bleibt draussen). 1275 Tests gruen.
ci.yml ist auf main wieder gruen: Run 292 auf f3c8074, alle neun Schritte
erfolgreich, einschliesslich "The distribution works as a fresh instance" - der Schritt, der
seit Run 279 rot war.
Version gebumpt (6.0.1, --patch --impact high) und Changeset geschrieben;
tools/CONTRACT.mds docs toc-Zeile und instructions/dev/doc-pull-through.md Schritt 3
nennen die .template-Form jetzt im Dateisatz. Die docs verify-Zeile leitet ihren Scope
von docs toc ab und brauchte keine Aenderung.

Herkunft

Gefunden beim Nachsehen der CI direkt nach dem 6.0.0-Release (Tag v6.0.0, Commit 5d26698).
Der release.yml-Lauf war gruen, das Release korrekt getaggt - der Defekt sass im ausgelieferten
Artefakt, nicht im Release-Vorgang. Behoben in Commit f3c8074, freigegeben als 6.0.1.

Kein docs/-Dokument hat seine Begruendung verloren: ownership-and-templates.md beschreibt die
Ownership-Frage, und die bleibt unveraendert - ein .template war schon vorher stack-eigen, es
wurde nur nichts darin gepflegt.

## Befund (behoben in `6.0.1`) `kb/CONVENTIONS.md.template` war 105 Zeilen lang und trug keine ``-Region. Die TOC-Pflicht gilt fuer jede Referenzdatei ueber 100 Zeilen (`tools/chemenu/toc.py`, `THRESHOLD = 100`), und `kb/CONVENTIONS.md` steht in `toc.target_files()`. Eine Instanz, die das Template nach `instructions/setup-instance.md` adoptierte, bekam damit eine `kb/CONVENTIONS.md` ohne Region - und fiel am `tools/wikitool docs verify` in Schritt 13 derselben Anleitung (`instructions/setup-instance.md:264`) um: ``` ERROR Documentation issues found: - kb/CONVENTIONS.md needs a table-of-contents region refreshed - run `wikitool docs toc --apply` ``` Das war kein CI-Artefakt: der dokumentierte Installationsweg einer frisch ausgelieferten Instanz endete in einem roten `docs verify`. Ausgeliefert war der Defekt in `6.0.0`, behoben in `6.0.1`. ## Ursache `toc.target_files()` berechnete den Dateisatz ueber die *adoptierten* Namen - `kb/CONVENTIONS.md`, `kb/*/COLLECTION.md`, `instructions/**.md`, `types/*.md`, `docs/*.md`. Eine `.template`-Datei endet auf `.md.template` und fiel damit aus jedem dieser Walks heraus: `docs toc --apply` hat das Template nie angefasst, `docs verify` es nie gelesen. Geprueft wurde erst die adoptierte Kopie, die es im Ursprungs-Repo gar nicht gibt. Solange das Template unter 100 Zeilen blieb, war das folgenlos. `f350999` (2026-09-15, "Control-Plane-Sprache universell") hat es von 99 auf 105 Zeilen wachsen lassen - genau ueber die Schwelle: | Commit | Zeilen | CI | |---|---|---| | `c64479f` | 99 | gruen (Run 274) | | `f350999` | 105 | **rot (Run 279)** | Seither war `ci.yml` auf jedem Push rot (Runs 279, 281, 282, 284, 285, 287, 289). Dass es wie Flackern aussah, lag an der Paarung: jeder Push erzeugt zusaetzlich einen `release.yml`-Lauf, und der ist gruen. Die gruen/rot-Paare pro Commit sind zwei verschiedene Workflows, keine Wiederholungslaeufe - diese Fehllesung hat den roten Zustand fuenf Pushes lang ueberlebt. ## Entscheidung und Umsetzung Umgesetzt wie vorgeschlagen: **eine in Scope stehende Datei nimmt ihr `<name>.template` mit hinein**, wenn eines existiert (`toc.target_files()`). Das Template ist dasselbe Dokument einen Schritt frueher in seinem Leben; wer es auslaesst, laesst die adoptierte Kopie den Fehler erben. Der Scope bleibt berechnet statt handgepflegt, also sind `types/*.md.template` und `kb/*/COLLECTION.md.template` automatisch mit abgedeckt, sobald eines ueber die Schwelle waechst. Verworfen, wie im urspruenglichen Vorschlag: - **Template unter 100 Zeilen kuerzen** - haelt bis zum naechsten Absatz. - **`docs toc --apply` im CI-Replay nach der Adoption** - repariert den Testpfad und laesst den echten Nutzerpfad kaputt. Die offene Frage ist beantwortet: die Platzhalter des Templates (`{language}`) kollidieren nicht - die Ueberschriften sind Klartext, `docs toc --apply` erzeugt eine korrekte Region. **Grenzuebertritt geprueft und verneint.** Das Template ist stack-eigen (`ownership.is_stack_owned`: jede `.template` unter einer Content-Stage), steht nicht in `UPGRADE_PRESERVED_PATHS`, und `dist upgrade` schreibt es damit mit - eine Instanz bekommt das reparierte Template durch den Upgrade selbst, ohne Handarbeit. Der Rueckweg funktioniert ebenso, weil die alte Maschinerie das Template gar nicht prueft. Handarbeit faellt nur an, wo eine Instanz ihr stack-eigenes Template lokal veraendert hat; `dist upgrade` meldet genau das als `blocked` und verlangt `--keep-local`. Daher `--patch`, kein `--breaking`. Nebenbei aufgeraeumt: `docs_verify.TEMPLATE_SUFFIX` war eine zweite Schreibung derselben Konstante und kommt jetzt aus `toc` (kein Zyklus - `docs_verify` importiert `toc` ohnehin). `ownership.py` behaelt seine eigene bewusst: andere Frage, engerer Scope. ## Akzeptanzkriterien - [x] Nach `dist export` + Adoption der Templates laeuft `tools/wikitool docs verify` in der frischen Instanz ohne Befund durch. Verifiziert per vollstaendigem `setup-instance.md`-Replay gegen einen frischen Export: `doctor`, `docs verify` (59 Referenzdateien), `instructions verify` und `lint --fail-on-error` gruen. - [x] `docs toc --apply` haelt `kb/CONVENTIONS.md.template` im Ursprungs-Repo aktuell; die Region ist vom Werkzeug geschrieben, nicht von Hand. `docs verify` prueft dort jetzt 57 statt 56 Referenzdateien. - [x] Test deckt den Fall ab: `test_a_shipped_template_over_the_threshold_without_a_region_is_reported` - ein `.template` ueber der Schwelle ohne Region ist ein Befund. Dazu `test_target_files_takes_the_shipped_template_of_a_file_in_scope` und `test_target_files_takes_a_template_only_for_a_file_already_in_scope` (ein `USER.md.template` ohne Referenzdatei daneben bleibt draussen). 1275 Tests gruen. - [x] `ci.yml` ist auf `main` wieder gruen: **Run 292** auf `f3c8074`, alle neun Schritte erfolgreich, einschliesslich "The distribution works as a fresh instance" - der Schritt, der seit Run 279 rot war. - [x] Version gebumpt (`6.0.1`, `--patch --impact high`) und Changeset geschrieben; `tools/CONTRACT.md`s `docs toc`-Zeile und `instructions/dev/doc-pull-through.md` Schritt 3 nennen die `.template`-Form jetzt im Dateisatz. Die `docs verify`-Zeile leitet ihren Scope von `docs toc` ab und brauchte keine Aenderung. ## Herkunft Gefunden beim Nachsehen der CI direkt nach dem `6.0.0`-Release (Tag `v6.0.0`, Commit `5d26698`). Der `release.yml`-Lauf war gruen, das Release korrekt getaggt - der Defekt sass im ausgelieferten Artefakt, nicht im Release-Vorgang. Behoben in Commit `f3c8074`, freigegeben als `6.0.1`. Kein `docs/`-Dokument hat seine Begruendung verloren: `ownership-and-templates.md` beschreibt die Ownership-Frage, und die bleibt unveraendert - ein `.template` war schon vorher stack-eigen, es wurde nur nichts darin gepflegt.

torben added the prio/blocking size/M area/distribution kind/defect labels 2026-09-15 20:28:19 +00:00

torben referenced this issue from a commit

2026-09-16 04:44:59 +00:00

docs toc/verify: die .template-Form einer Referenzdatei steht im Dateisatz, Version 6.0.1 freigegeben (schliesst #106)

torben commented

2026-09-16 04:48:37 +00:00

Changelog: Body auf den Endstand geschrieben. Loesungsvorschlag ist jetzt die getroffene Entscheidung (toc.target_files() nimmt das .template einer in Scope stehenden Datei mit), die offene Frage zu den {language}-Platzhaltern ist beantwortet (keine Kollision), die Grenzuebertritt-Pruefung mit ihrer Begruendung ergaenzt (--patch, weil dist upgrade das stack-eigene Template selbst mitschreibt). Alle fuenf Akzeptanzkriterien abgehakt und mit dem benannt, was sie belegt - Run 292 fuer die gruene CI, der setup-instance.md-Replay fuer die frische Instanz. Behoben in f3c8074, freigegeben als 6.0.1.

**Changelog:** Body auf den Endstand geschrieben. Loesungsvorschlag ist jetzt die getroffene Entscheidung (`toc.target_files()` nimmt das `.template` einer in Scope stehenden Datei mit), die offene Frage zu den `{language}`-Platzhaltern ist beantwortet (keine Kollision), die Grenzuebertritt-Pruefung mit ihrer Begruendung ergaenzt (`--patch`, weil `dist upgrade` das stack-eigene Template selbst mitschreibt). Alle fuenf Akzeptanzkriterien abgehakt und mit dem benannt, was sie belegt - Run 292 fuer die gruene CI, der `setup-instance.md`-Replay fuer die frische Instanz. Behoben in `f3c8074`, freigegeben als `6.0.1`.

torben closed this issue

2026-09-16 04:48:40 +00:00

torben referenced this issue

2026-09-16 06:08:51 +00:00

Upgrade-Lauf 5.0.0 -> 6.0.0 auf ausgelieferter Instanz: Laufbericht, Telemetrie, vier Befunde #107

Sign in to join this conversation.