kb/CONVENTIONS.md.template war 105 Zeilen lang und trug keine <!-- wikitool:toc -->-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 `<!-- wikitool:toc -->`-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.
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`.
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.
Befund (behoben in
6.0.1)kb/CONVENTIONS.md.templatewar 105 Zeilen lang und trug keine<!-- wikitool:toc -->-Region.Die TOC-Pflicht gilt fuer jede Referenzdatei ueber 100 Zeilen (
tools/chemenu/toc.py,THRESHOLD = 100), undkb/CONVENTIONS.mdsteht intoc.target_files(). Eine Instanz, die dasTemplate nach
instructions/setup-instance.mdadoptierte, bekam damit einekb/CONVENTIONS.mdohne Region - und fiel am
tools/wikitool docs verifyin Schritt 13 derselben Anleitung(
instructions/setup-instance.md:264) um:Das war kein CI-Artefakt: der dokumentierte Installationsweg einer frisch ausgelieferten Instanz
endete in einem roten
docs verify. Ausgeliefert war der Defekt in6.0.0, behoben in6.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.templateund fiel damit aus jedem dieser Walks heraus:docs toc --applyhat das Template nie angefasst,docs verifyes nie gelesen. Geprueft wurdeerst 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:
c64479ff350999Seither war
ci.ymlauf jedem Push rot (Runs 279, 281, 282, 284, 285, 287, 289). Dass es wieFlackern aussah, lag an der Paarung: jeder Push erzeugt zusaetzlich einen
release.yml-Lauf, undder 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>.templatemithinein, wenn eines existiert (
toc.target_files()). Das Template ist dasselbe Dokument einenSchritt frueher in seinem Leben; wer es auslaesst, laesst die adoptierte Kopie den Fehler erben.
Der Scope bleibt berechnet statt handgepflegt, also sind
types/*.md.templateundkb/*/COLLECTION.md.templateautomatisch mit abgedeckt, sobald eines ueber die Schwelle waechst.Verworfen, wie im urspruenglichen Vorschlag:
docs toc --applyim CI-Replay nach der Adoption - repariert den Testpfad und laesst denechten Nutzerpfad kaputt.
Die offene Frage ist beantwortet: die Platzhalter des Templates (
{language}) kollidieren nicht -die Ueberschriften sind Klartext,
docs toc --applyerzeugt eine korrekte Region.Grenzuebertritt geprueft und verneint. Das Template ist stack-eigen
(
ownership.is_stack_owned: jede.templateunter einer Content-Stage), steht nicht inUPGRADE_PRESERVED_PATHS, unddist upgradeschreibt es damit mit - eine Instanz bekommt dasreparierte 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 upgrademeldet genau das alsblockedundverlangt
--keep-local. Daher--patch, kein--breaking.Nebenbei aufgeraeumt:
docs_verify.TEMPLATE_SUFFIXwar eine zweite Schreibung derselben Konstanteund kommt jetzt aus
toc(kein Zyklus -docs_verifyimportierttocohnehin).ownership.pybehaelt seine eigene bewusst: andere Frage, engerer Scope.
Akzeptanzkriterien
dist export+ Adoption der Templates laeufttools/wikitool docs verifyin derfrischen Instanz ohne Befund durch. Verifiziert per vollstaendigem
setup-instance.md-Replay gegen einen frischen Export:doctor,docs verify(59 Referenzdateien),
instructions verifyundlint --fail-on-errorgruen.docs toc --applyhaeltkb/CONVENTIONS.md.templateim Ursprungs-Repo aktuell; die Regionist vom Werkzeug geschrieben, nicht von Hand.
docs verifyprueft dort jetzt 57 statt 56Referenzdateien.
test_a_shipped_template_over_the_threshold_without_a_region_is_reported- ein.templateueber der Schwelle ohne Region ist ein Befund. Dazu
test_target_files_takes_the_shipped_template_of_a_file_in_scopeundtest_target_files_takes_a_template_only_for_a_file_already_in_scope(einUSER.md.templateohne Referenzdatei daneben bleibt draussen). 1275 Tests gruen.
ci.ymlist aufmainwieder gruen: Run 292 auff3c8074, alle neun Schritteerfolgreich, einschliesslich "The distribution works as a fresh instance" - der Schritt, der
seit Run 279 rot war.
6.0.1,--patch --impact high) und Changeset geschrieben;tools/CONTRACT.mdsdocs toc-Zeile undinstructions/dev/doc-pull-through.mdSchritt 3nennen die
.template-Form jetzt im Dateisatz. Diedocs verify-Zeile leitet ihren Scopevon
docs tocab und brauchte keine Aenderung.Herkunft
Gefunden beim Nachsehen der CI direkt nach dem
6.0.0-Release (Tagv6.0.0, Commit5d26698).Der
release.yml-Lauf war gruen, das Release korrekt getaggt - der Defekt sass im ausgeliefertenArtefakt, nicht im Release-Vorgang. Behoben in Commit
f3c8074, freigegeben als6.0.1.Kein
docs/-Dokument hat seine Begruendung verloren:ownership-and-templates.mdbeschreibt dieOwnership-Frage, und die bleibt unveraendert - ein
.templatewar schon vorher stack-eigen, eswurde nur nichts darin gepflegt.
Changelog: Body auf den Endstand geschrieben. Loesungsvorschlag ist jetzt die getroffene Entscheidung (
toc.target_files()nimmt das.templateeiner in Scope stehenden Datei mit), die offene Frage zu den{language}-Platzhaltern ist beantwortet (keine Kollision), die Grenzuebertritt-Pruefung mit ihrer Begruendung ergaenzt (--patch, weildist upgradedas stack-eigene Template selbst mitschreibt). Alle fuenf Akzeptanzkriterien abgehakt und mit dem benannt, was sie belegt - Run 292 fuer die gruene CI, dersetup-instance.md-Replay fuer die frische Instanz. Behoben inf3c8074, freigegeben als6.0.1.