Erledigt in 4.3.1, Commit 4e80a07. CI-Runs 130 (Verify + dist-export-Replay) und 131 (Release) grün.
Ausgangslage
docs/ ist in #38 (4.3.0, Commit 0b8ca74) als inertes, ausgeliefertes Verzeichnis entstanden: Prosa ohne Frontmatter, ohne Typ, ohne Index, ohne Lint, ohne Decay. Kein wikitool-Befehl fasst es an ausser dist export, das es verbatim kopiert. Dieses Issue war die Inhaltsarbeit, die danach kam.
Das Verzeichnis existierte im Arbeitsbaum noch nicht — git verfolgt keine leeren Verzeichnisse, und eine Platzhalterdatei waere Inhalt vor seiner Zeit gewesen. Die erste hier geschriebene Seite hat es angelegt; _copy_tree brauchte dafuer keine Aenderung (dist_cmd.py:213 liefert bei fehlendem source_root still ein leeres Dict). Das hat sich bestaetigt: am Export war nichts anzupassen.
Warum das gebraucht wurde:dist export liefert keine einzige kb/-Seite aus (find_leaks, tools/chemenu/commands/dist_cmd.py:455). Eine frische Instanz bekam damit den Stack, aber keinen Grund fuer seine Form. README.md und INSTALL.md beschreiben Bedienung, nicht Begruendung.
Zielgruppe
Nicht auf Entwickler beschraenkt: jede Sitzung — Agent oder Mensch —, die ueber den Basisbetrieb hinauswill. On-demand-Zugriff wie instructions/, aber ohne deren Bindungskraft: kein Skill, kein automatischer Ladepfad.
Die eine Regel
docs/ enthaelt keinen normativen Satz. Was binden wuerde, gehoert in einen Contract oder nach AGENTS.md. Das ist der Grund, warum es nichts zu verifizieren gibt: Hintergrund kann veralten, aber nicht mit einer zweiten Kopie derselben Regel driften — AGENTS.md Invariante 8 bleibt unberuehrt.
Erklaerung, nicht Vorschrift. Ein docs/-Text sagt "warum das so gebaut ist", nie "so ist es zu tun".
Seit #38 steht diese Regel in AGENTS.md § File naming, zusammen mit der docs/-Zeile in der Tabelle und dem Routing-Eintrag. Alle vier hier geschriebenen Seiten halten sie ein.
Abgrenzung gegen kb/
Ueberschneidung ist zulaessig und kein Verstoss, solange die Rollen sauber bleiben:
sagt
Beleg
kb/concepts/KB Stack Versioning.md
diese Instanz hat am Datum X entschieden
sources: auf ein Transkript in raw/
docs/-Seite zum Versionsmodell
der Stack funktioniert so, aus diesen Gruenden
keiner, und braucht keinen
Deshalb wurde docs/frisch geschrieben, nicht durch Umzug befuellt. Keine der vier Seiten traegt sources: auf Transkripte, die ein Empfaenger nicht hat.
Umfang: gedeckelt
Vier Seiten zum Start, danach waechst docs/ nur mit Anlass. Alle vier Kandidaten wurden geschrieben:
Pipeline-Rationale → docs/pipeline-rationale.md — warum raw/ -> types/+tools/ -> kb/ -> reports/ vier getrennte Stufen sind und was "never re-derive, always compile" praktisch heisst
Warum Gates in Code stehen → docs/why-gates-are-code.md — die Begruendung hinter Mass-Update-, Publish-Remote- und Iteration-Gate: ein Prompt-Limit ist eines, an dem ein Agent sich vorbeireden kann
Ownership- und .template-Modell → docs/ownership-and-templates.md — was stack-eigen ist und was der Instanz gehoert, warum kb/CONTRACT.md verbatim ausgeliefert wird und kb/CONVENTIONS.md nur als Template
Versionsmodell → docs/version-model.md — Drop-in-Kompatibilitaet und Migrationsbedarf als zwei unabhaengige Fragen, illustriert an der 2.0.0-Fallstudie
Wer haelt docs/ aktuell
Bis zu diesem Issue: niemand. AGENTS.md § Changelog trug die Regel "A stack change is not finished until the human docs describe it" und nannte dort nur README.md, EVALS.md und tools/README.md — docs/ fehlte. #38 hatte die Luecke nicht geschlossen, und ohne Klausel veraltet der Hintergrund genau dort, wo er am teuersten ist: in einer ausgelieferten Instanz, die die Begruendung nicht gegenpruefen kann.
Umgesetzt: die Klausel steht an genau einer Stelle, AGENTS.md § Changelog (heute Zeilen 279-284), wo die Zwillingsregel schon stand und die jede Sitzung ohnehin im Kontext hat. Ausdruecklich nicht als wiederholte Anforderung in jedem bearbeiteten Issue — das waere die zweite Kopie, die driftet (Invariante 8), und laut instructions/dev/issue-tracking.md § "What no tool checks" prueft am Board ohnehin nichts.
Sie fuhr in diesem Issue mit statt als eigenes: eine Pflegeregel fuer ein Verzeichnis ohne Seiten ist eine Regel ueber nichts, und so war es ein Satz im selben Commit statt eines eigenen PATCH-Bumps.
Der Unterschied zu den drei bestehenden Dateien steht in der Klausel, sonst wuerde sie falsch gelesen: README.md/EVALS.md/tools/README.md spiegeln was der Stack ist und veralten bei jedem neuen Flag; eine docs/-Seite haelt einen Grund fest und veraltet nur, wenn eine aufgeschriebene Begruendung nicht mehr traegt. Geprueft wird das per Konstruktion nicht: kein normativer Satz, also nichts zu verifizieren, nur etwas zu pflegen.
Akzeptanzkriterien
Drei bis vier Seiten geschrieben, keine davon mit einem normativen Satz — vier Seiten, siehe oben
Jede Seite verlinkt auf die bindenden Dokumente statt deren Regeln zu wiederholen — version-model.md etwa schliesst mit "Where the procedure lives" auf instructions/dev/version-parts.md
AGENTS.md § Changelog um docs/ erweitert: welche Art Aenderung eine Hintergrundseite entwertet, und dass das per Konstruktion ungeprueft bleibt — Zeilen 279-284
dist export traegt die Seiten in eine frische Instanz — belegt durch CI-Run 130 auf 4e80a07 (Schritt "The distribution works as a fresh instance"), nicht nur durch die Export-Zeile in tools/CONTRACT.md
Version-Bump: PATCH fuer die AGENTS.md-Klausel; die Prosa in docs/ selbst begruendet keinen Bump — 4.3.0 → 4.3.1
Verifikation
docs verify, instructions verify und die Testsuite (869 Tests) laufen auf dem Stand dieses Commits gruen; CI-Runs 130 und 131 bestaetigen dasselbe inklusive dist-export-Replay gegen eine frische Instanz.
Abhaengigkeit
Keine. #38 ist am 2026-09-03 gelandet (4.3.0); status/blocked war davor entfernt worden.
Vorgeschichte
Abgespalten von #38 am 2026-09-03, als dessen Zuschnitt von "Entscheidungsseiten umziehen" auf "Hintergrund bekommt einen ausgelieferten Ort, Decision-Seiten bleiben in kb/" korrigiert wurde. Am selben Tag, nach dem Landen von #38, um die Pflegefrage ergaenzt.
Nachtrag 2026-09-03: Prozessfehler beim Abschluss, und was daraus folgte
Dieser Body wurde nach dem Schliessen auf den Endstand gebracht. Die Sitzung, die das Issue umgesetzt und geschlossen hat (Sonnet/medium, frische Sitzung mit stack-dev), hat instructions/dev/issue-tracking.md Schritt 7 nicht befolgt und einen gruendlichen Abschlusskommentar ueber einem Body mit unangehakten Kriterien hinterlassen — derselbe Fehlermodus, den 4.1.2 (#44) eine Stunde zuvor benannt hatte.
Ursache, ermittelt am Skill-Layer: nicht der Text der Regel, sondern ihre Erreichbarkeit. Die nummerierten Schritte von stack-dev/SKILL.md endeten bei "Verify before publishing"; ein Issue zu schliessen war ueberhaupt kein Schritt, sondern haengte an einem Zeiger innerhalb von Schritt 2 — einer Routing-Tabelle, keiner Checkliste. 4.1.2 hatte issue-tracking.md um 101 Zeilen erweitert und im Skill nur den Blurb umformuliert, dessen fett gesetztes "not at the end" die Abschlusspflicht zusaetzlich verdeckte.
Behoben in 4.3.2, Commit 56ecfc7: neuer nummerierter Schritt 5 im Skill ("Close the issue with a body rewrite, not a comment") mit dem Test inline, und der Schritt-2-Blurb rebalanciert. Begruendung in voller Laenge im CHANGES.md-Eintrag zu 4.3.2.
Der Release-Drafter-Punkt, der in #42 zurueckgestellt war, hat seit demselben Tag ein eigenes Issue: #46.
**Erledigt in 4.3.1, Commit `4e80a07`.** CI-Runs 130 (Verify + dist-export-Replay) und 131 (Release) grün.
## Ausgangslage
`docs/` ist in #38 (4.3.0, Commit `0b8ca74`) als inertes, ausgeliefertes Verzeichnis entstanden: Prosa ohne Frontmatter, ohne Typ, ohne Index, ohne Lint, ohne Decay. Kein `wikitool`-Befehl fasst es an ausser `dist export`, das es verbatim kopiert. Dieses Issue war die Inhaltsarbeit, die danach kam.
Das Verzeichnis existierte im Arbeitsbaum noch nicht — git verfolgt keine leeren Verzeichnisse, und eine Platzhalterdatei waere Inhalt vor seiner Zeit gewesen. Die erste hier geschriebene Seite hat es angelegt; `_copy_tree` brauchte dafuer keine Aenderung (`dist_cmd.py:213` liefert bei fehlendem `source_root` still ein leeres Dict). Das hat sich bestaetigt: am Export war nichts anzupassen.
**Warum das gebraucht wurde:** `dist export` liefert keine einzige `kb/`-Seite aus (`find_leaks`, `tools/chemenu/commands/dist_cmd.py:455`). Eine frische Instanz bekam damit den Stack, aber keinen Grund fuer seine Form. `README.md` und `INSTALL.md` beschreiben Bedienung, nicht Begruendung.
## Zielgruppe
Nicht auf Entwickler beschraenkt: jede Sitzung — Agent oder Mensch —, die ueber den Basisbetrieb hinauswill. On-demand-Zugriff wie `instructions/`, aber ohne deren Bindungskraft: kein Skill, kein automatischer Ladepfad.
## Die eine Regel
**`docs/` enthaelt keinen normativen Satz.** Was binden wuerde, gehoert in einen Contract oder nach `AGENTS.md`. Das ist der Grund, warum es nichts zu verifizieren gibt: Hintergrund kann veralten, aber nicht mit einer zweiten Kopie derselben Regel driften — AGENTS.md Invariante 8 bleibt unberuehrt.
Erklaerung, nicht Vorschrift. Ein `docs/`-Text sagt "warum das so gebaut ist", nie "so ist es zu tun".
Seit #38 steht diese Regel in `AGENTS.md` § File naming, zusammen mit der `docs/`-Zeile in der Tabelle und dem Routing-Eintrag. Alle vier hier geschriebenen Seiten halten sie ein.
## Abgrenzung gegen `kb/`
Ueberschneidung ist zulaessig und kein Verstoss, solange die Rollen sauber bleiben:
| | sagt | Beleg |
|---|---|---|
| `kb/concepts/KB Stack Versioning.md` | *diese Instanz* hat am Datum X entschieden | `sources:` auf ein Transkript in `raw/` |
| `docs/`-Seite zum Versionsmodell | *der Stack* funktioniert so, aus diesen Gruenden | keiner, und braucht keinen |
Deshalb wurde `docs/` **frisch geschrieben, nicht durch Umzug befuellt**. Keine der vier Seiten traegt `sources:` auf Transkripte, die ein Empfaenger nicht hat.
## Umfang: gedeckelt
Vier Seiten zum Start, danach waechst `docs/` nur mit Anlass. Alle vier Kandidaten wurden geschrieben:
- [x] **Pipeline-Rationale** → `docs/pipeline-rationale.md` — warum `raw/ -> types/+tools/ -> kb/ -> reports/` vier getrennte Stufen sind und was "never re-derive, always compile" praktisch heisst
- [x] **Warum Gates in Code stehen** → `docs/why-gates-are-code.md` — die Begruendung hinter Mass-Update-, Publish-Remote- und Iteration-Gate: ein Prompt-Limit ist eines, an dem ein Agent sich vorbeireden kann
- [x] **Ownership- und `.template`-Modell** → `docs/ownership-and-templates.md` — was stack-eigen ist und was der Instanz gehoert, warum `kb/CONTRACT.md` verbatim ausgeliefert wird und `kb/CONVENTIONS.md` nur als Template
- [x] **Versionsmodell** → `docs/version-model.md` — Drop-in-Kompatibilitaet und Migrationsbedarf als zwei unabhaengige Fragen, illustriert an der 2.0.0-Fallstudie
## Wer haelt `docs/` aktuell
Bis zu diesem Issue: niemand. `AGENTS.md` § Changelog trug die Regel "A stack change is not finished until the human docs describe it" und nannte dort nur `README.md`, `EVALS.md` und `tools/README.md` — `docs/` fehlte. #38 hatte die Luecke nicht geschlossen, und ohne Klausel veraltet der Hintergrund genau dort, wo er am teuersten ist: in einer ausgelieferten Instanz, die die Begruendung nicht gegenpruefen kann.
**Umgesetzt:** die Klausel steht an genau einer Stelle, `AGENTS.md` § Changelog (heute Zeilen 279-284), wo die Zwillingsregel schon stand und die jede Sitzung ohnehin im Kontext hat. Ausdruecklich **nicht** als wiederholte Anforderung in jedem bearbeiteten Issue — das waere die zweite Kopie, die driftet (Invariante 8), und laut `instructions/dev/issue-tracking.md` § "What no tool checks" prueft am Board ohnehin nichts.
Sie fuhr in diesem Issue mit statt als eigenes: eine Pflegeregel fuer ein Verzeichnis ohne Seiten ist eine Regel ueber nichts, und so war es ein Satz im selben Commit statt eines eigenen PATCH-Bumps.
Der Unterschied zu den drei bestehenden Dateien steht in der Klausel, sonst wuerde sie falsch gelesen: `README.md`/`EVALS.md`/`tools/README.md` spiegeln *was der Stack ist* und veralten bei jedem neuen Flag; eine `docs/`-Seite haelt einen **Grund** fest und veraltet nur, wenn eine aufgeschriebene Begruendung nicht mehr traegt. Geprueft wird das per Konstruktion nicht: kein normativer Satz, also nichts zu verifizieren, nur etwas zu pflegen.
## Akzeptanzkriterien
- [x] Drei bis vier Seiten geschrieben, keine davon mit einem normativen Satz — vier Seiten, siehe oben
- [x] Jede Seite verlinkt auf die bindenden Dokumente statt deren Regeln zu wiederholen — `version-model.md` etwa schliesst mit "Where the procedure lives" auf `instructions/dev/version-parts.md`
- [x] `AGENTS.md` § Changelog um `docs/` erweitert: welche Art Aenderung eine Hintergrundseite entwertet, und dass das per Konstruktion ungeprueft bleibt — Zeilen 279-284
- [x] `dist export` traegt die Seiten in eine frische Instanz — belegt durch CI-Run 130 auf `4e80a07` (Schritt "The distribution works as a fresh instance"), nicht nur durch die Export-Zeile in `tools/CONTRACT.md`
- [x] Version-Bump: PATCH fuer die `AGENTS.md`-Klausel; die Prosa in `docs/` selbst begruendet keinen Bump — 4.3.0 → 4.3.1
## Verifikation
`docs verify`, `instructions verify` und die Testsuite (869 Tests) laufen auf dem Stand dieses Commits gruen; CI-Runs 130 und 131 bestaetigen dasselbe inklusive dist-export-Replay gegen eine frische Instanz.
## Abhaengigkeit
Keine. **#38 ist am 2026-09-03 gelandet** (4.3.0); `status/blocked` war davor entfernt worden.
## Vorgeschichte
Abgespalten von #38 am 2026-09-03, als dessen Zuschnitt von "Entscheidungsseiten umziehen" auf "Hintergrund bekommt einen ausgelieferten Ort, Decision-Seiten bleiben in `kb/`" korrigiert wurde. Am selben Tag, nach dem Landen von #38, um die Pflegefrage ergaenzt.
## Nachtrag 2026-09-03: Prozessfehler beim Abschluss, und was daraus folgte
Dieser Body wurde **nach** dem Schliessen auf den Endstand gebracht. Die Sitzung, die das Issue umgesetzt und geschlossen hat (Sonnet/medium, frische Sitzung mit `stack-dev`), hat `instructions/dev/issue-tracking.md` Schritt 7 nicht befolgt und einen gruendlichen Abschlusskommentar ueber einem Body mit unangehakten Kriterien hinterlassen — derselbe Fehlermodus, den 4.1.2 (#44) eine Stunde zuvor benannt hatte.
**Ursache, ermittelt am Skill-Layer:** nicht der Text der Regel, sondern ihre Erreichbarkeit. Die nummerierten Schritte von `stack-dev/SKILL.md` endeten bei "Verify before publishing"; ein Issue zu schliessen war ueberhaupt kein Schritt, sondern haengte an einem Zeiger innerhalb von Schritt 2 — einer Routing-Tabelle, keiner Checkliste. 4.1.2 hatte `issue-tracking.md` um 101 Zeilen erweitert und im Skill nur den Blurb umformuliert, dessen fett gesetztes "not at the end" die Abschlusspflicht zusaetzlich verdeckte.
**Behoben in 4.3.2, Commit `56ecfc7`:** neuer nummerierter Schritt 5 im Skill ("Close the issue with a body rewrite, not a comment") mit dem Test inline, und der Schritt-2-Blurb rebalanciert. Begruendung in voller Laenge im `CHANGES.md`-Eintrag zu 4.3.2.
Der Release-Drafter-Punkt, der in #42 zurueckgestellt war, hat seit demselben Tag ein eigenes Issue: #46.
Changelog:#38 ist gelandet (4.3.0, Commit 0b8ca74) — status/blocked entfernt, Abhaengigkeitsabschnitt entsprechend neu geschrieben. Ausgangslage praezisiert: das Verzeichnis existiert noch nicht im Arbeitsbaum, die erste hier geschriebene Seite legt es an.
Neuer Abschnitt "Wer haelt docs/ aktuell": die Pflegefrage war nirgends hinterlegt. AGENTS.md § Changelog nennt README.md/EVALS.md/tools/README.md, aber nicht docs/. Entschieden, die Klausel dort und nur dort zu ergaenzen — nicht als wiederholte Anforderung pro Issue (zweite Kopie, Invariante 8; am Board prueft ohnehin nichts, siehe instructions/dev/issue-tracking.md). Faehrt in diesem Issue mit statt als eigenes: eine Pflegeregel fuer ein Verzeichnis ohne Seiten ist eine Regel ueber nichts.
Akzeptanzkriterien um die Klausel erweitert und um die Bump-Frage praezisiert: PATCH fuer die AGENTS.md-Aenderung, die docs/-Prosa selbst begruendet keinen Bump.
**Changelog:** #38 ist gelandet (4.3.0, Commit `0b8ca74`) — `status/blocked` entfernt, Abhaengigkeitsabschnitt entsprechend neu geschrieben. Ausgangslage praezisiert: das Verzeichnis existiert noch nicht im Arbeitsbaum, die erste hier geschriebene Seite legt es an.
Neuer Abschnitt "Wer haelt `docs/` aktuell": die Pflegefrage war nirgends hinterlegt. `AGENTS.md` § Changelog nennt `README.md`/`EVALS.md`/`tools/README.md`, aber nicht `docs/`. Entschieden, die Klausel dort und nur dort zu ergaenzen — nicht als wiederholte Anforderung pro Issue (zweite Kopie, Invariante 8; am Board prueft ohnehin nichts, siehe `instructions/dev/issue-tracking.md`). Faehrt in diesem Issue mit statt als eigenes: eine Pflegeregel fuer ein Verzeichnis ohne Seiten ist eine Regel ueber nichts.
Akzeptanzkriterien um die Klausel erweitert und um die Bump-Frage praezisiert: PATCH fuer die `AGENTS.md`-Aenderung, die `docs/`-Prosa selbst begruendet keinen Bump.
Umgesetzt in 4.3.1 (Commit 4e80a07): vier Seiten in docs/, geschrieben von gezielt gebrieften Sub-Agents mit kontrolliertem Kontext (jeweils nur die relevanten Contracts/Instructions als Leseauftrag, keine Vorabkopie der Regeln in den Prompt).
docs/pipeline-rationale.md - warum raw -> types/tools -> kb -> reports vier getrennte Stufen sind, "never re-derive, always compile"
docs/why-gates-are-code.md - warum Mass-Update-, Publish-Remote- und Iteration-Budget-Gate in tools/wikitool statt in einer Instruktion stehen
docs/ownership-and-templates.md - stack-eigene verbatim-Dateien vs. instanz-eigene .template-Dateien
docs/version-model.md - Kompatibilitaet vs. Migration als unabhaengige Fragen, illustriert an der 2.0.0-Fallstudie
Alle vier ohne normativen Satz, jede verlinkt auf das bindende Dokument statt dessen Regeln zu wiederholen - gegengeprueft beim Review vor dem Publish.
AGENTS.md § Changelog um die Pflegeklausel ergaenzt (welche Art Aenderung eine docs/-Seite entwertet, und dass das per Konstruktion ungeprueft bleibt). Version-Bump PATCH (4.3.0 -> 4.3.1), da die Klausel Kontrollebene ist; die docs/-Prosa selbst begruendet keinen Bump.
dist export in ein Scratch-Verzeichnis verifiziert: alle vier Seiten landen dort unveraendert. docs verify, instructions verify und die volle Pytest-Suite (869 Tests) liefen gruen vor dem Publish.
Alle Akzeptanzkriterien erfuellt, schliesse das Issue.
Umgesetzt in 4.3.1 (Commit `4e80a07`): vier Seiten in `docs/`, geschrieben von gezielt gebrieften Sub-Agents mit kontrolliertem Kontext (jeweils nur die relevanten Contracts/Instructions als Leseauftrag, keine Vorabkopie der Regeln in den Prompt).
- `docs/pipeline-rationale.md` - warum `raw -> types/tools -> kb -> reports` vier getrennte Stufen sind, "never re-derive, always compile"
- `docs/why-gates-are-code.md` - warum Mass-Update-, Publish-Remote- und Iteration-Budget-Gate in `tools/wikitool` statt in einer Instruktion stehen
- `docs/ownership-and-templates.md` - stack-eigene verbatim-Dateien vs. instanz-eigene `.template`-Dateien
- `docs/version-model.md` - Kompatibilitaet vs. Migration als unabhaengige Fragen, illustriert an der 2.0.0-Fallstudie
Alle vier ohne normativen Satz, jede verlinkt auf das bindende Dokument statt dessen Regeln zu wiederholen - gegengeprueft beim Review vor dem Publish.
`AGENTS.md` § Changelog um die Pflegeklausel ergaenzt (welche Art Aenderung eine `docs/`-Seite entwertet, und dass das per Konstruktion ungeprueft bleibt). Version-Bump PATCH (4.3.0 -> 4.3.1), da die Klausel Kontrollebene ist; die `docs/`-Prosa selbst begruendet keinen Bump.
`dist export` in ein Scratch-Verzeichnis verifiziert: alle vier Seiten landen dort unveraendert. `docs verify`, `instructions verify` und die volle Pytest-Suite (869 Tests) liefen gruen vor dem Publish.
Alle Akzeptanzkriterien erfuellt, schliesse das Issue.
Changelog: Body nachträglich auf den Endstand gebracht — das Schließen am 17:41 hatte ihn als offene Arbeit stehen lassen.
Alle vier Seitenkandidaten und alle fünf Akzeptanzkriterien abgehakt, jeweils mit dem konkreten Beleg statt nur einem Haken (Dateipfade, AGENTS.md-Zeilen 279-284, CI-Run 130 für das dist-export-Kriterium). Zukunftsform auf Vergangenheit umgestellt, wo das Issue umgesetzte Dinge noch als Vorhaben beschrieb — insbesondere die Pflegeklausel und die _copy_tree-Annahme, die sich bestätigt hat. Verifikationsabschnitt ergänzt. Nachtrag am Ende hält fest, warum der Body nachgezogen wurde.
Issue bleibt geschlossen. Der Release-Drafter-Punkt aus #42 hat jetzt ein eigenes Issue: #46.
**Changelog:** Body nachträglich auf den Endstand gebracht — das Schließen am 17:41 hatte ihn als offene Arbeit stehen lassen.
Alle vier Seitenkandidaten und alle fünf Akzeptanzkriterien abgehakt, jeweils mit dem konkreten Beleg statt nur einem Haken (Dateipfade, `AGENTS.md`-Zeilen 279-284, CI-Run 130 für das dist-export-Kriterium). Zukunftsform auf Vergangenheit umgestellt, wo das Issue umgesetzte Dinge noch als Vorhaben beschrieb — insbesondere die Pflegeklausel und die `_copy_tree`-Annahme, die sich bestätigt hat. Verifikationsabschnitt ergänzt. Nachtrag am Ende hält fest, warum der Body nachgezogen wurde.
Issue bleibt geschlossen. Der Release-Drafter-Punkt aus #42 hat jetzt ein eigenes Issue: #46.
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.
Erledigt in 4.3.1, Commit
4e80a07. CI-Runs 130 (Verify + dist-export-Replay) und 131 (Release) grün.Ausgangslage
docs/ist in #38 (4.3.0, Commit0b8ca74) als inertes, ausgeliefertes Verzeichnis entstanden: Prosa ohne Frontmatter, ohne Typ, ohne Index, ohne Lint, ohne Decay. Keinwikitool-Befehl fasst es an ausserdist export, das es verbatim kopiert. Dieses Issue war die Inhaltsarbeit, die danach kam.Das Verzeichnis existierte im Arbeitsbaum noch nicht — git verfolgt keine leeren Verzeichnisse, und eine Platzhalterdatei waere Inhalt vor seiner Zeit gewesen. Die erste hier geschriebene Seite hat es angelegt;
_copy_treebrauchte dafuer keine Aenderung (dist_cmd.py:213liefert bei fehlendemsource_rootstill ein leeres Dict). Das hat sich bestaetigt: am Export war nichts anzupassen.Warum das gebraucht wurde:
dist exportliefert keine einzigekb/-Seite aus (find_leaks,tools/chemenu/commands/dist_cmd.py:455). Eine frische Instanz bekam damit den Stack, aber keinen Grund fuer seine Form.README.mdundINSTALL.mdbeschreiben Bedienung, nicht Begruendung.Zielgruppe
Nicht auf Entwickler beschraenkt: jede Sitzung — Agent oder Mensch —, die ueber den Basisbetrieb hinauswill. On-demand-Zugriff wie
instructions/, aber ohne deren Bindungskraft: kein Skill, kein automatischer Ladepfad.Die eine Regel
docs/enthaelt keinen normativen Satz. Was binden wuerde, gehoert in einen Contract oder nachAGENTS.md. Das ist der Grund, warum es nichts zu verifizieren gibt: Hintergrund kann veralten, aber nicht mit einer zweiten Kopie derselben Regel driften — AGENTS.md Invariante 8 bleibt unberuehrt.Erklaerung, nicht Vorschrift. Ein
docs/-Text sagt "warum das so gebaut ist", nie "so ist es zu tun".Seit #38 steht diese Regel in
AGENTS.md§ File naming, zusammen mit derdocs/-Zeile in der Tabelle und dem Routing-Eintrag. Alle vier hier geschriebenen Seiten halten sie ein.Abgrenzung gegen
kb/Ueberschneidung ist zulaessig und kein Verstoss, solange die Rollen sauber bleiben:
kb/concepts/KB Stack Versioning.mdsources:auf ein Transkript inraw/docs/-Seite zum VersionsmodellDeshalb wurde
docs/frisch geschrieben, nicht durch Umzug befuellt. Keine der vier Seiten traegtsources:auf Transkripte, die ein Empfaenger nicht hat.Umfang: gedeckelt
Vier Seiten zum Start, danach waechst
docs/nur mit Anlass. Alle vier Kandidaten wurden geschrieben:docs/pipeline-rationale.md— warumraw/ -> types/+tools/ -> kb/ -> reports/vier getrennte Stufen sind und was "never re-derive, always compile" praktisch heisstdocs/why-gates-are-code.md— die Begruendung hinter Mass-Update-, Publish-Remote- und Iteration-Gate: ein Prompt-Limit ist eines, an dem ein Agent sich vorbeireden kann.template-Modell →docs/ownership-and-templates.md— was stack-eigen ist und was der Instanz gehoert, warumkb/CONTRACT.mdverbatim ausgeliefert wird undkb/CONVENTIONS.mdnur als Templatedocs/version-model.md— Drop-in-Kompatibilitaet und Migrationsbedarf als zwei unabhaengige Fragen, illustriert an der 2.0.0-FallstudieWer haelt
docs/aktuellBis zu diesem Issue: niemand.
AGENTS.md§ Changelog trug die Regel "A stack change is not finished until the human docs describe it" und nannte dort nurREADME.md,EVALS.mdundtools/README.md—docs/fehlte. #38 hatte die Luecke nicht geschlossen, und ohne Klausel veraltet der Hintergrund genau dort, wo er am teuersten ist: in einer ausgelieferten Instanz, die die Begruendung nicht gegenpruefen kann.Umgesetzt: die Klausel steht an genau einer Stelle,
AGENTS.md§ Changelog (heute Zeilen 279-284), wo die Zwillingsregel schon stand und die jede Sitzung ohnehin im Kontext hat. Ausdruecklich nicht als wiederholte Anforderung in jedem bearbeiteten Issue — das waere die zweite Kopie, die driftet (Invariante 8), und lautinstructions/dev/issue-tracking.md§ "What no tool checks" prueft am Board ohnehin nichts.Sie fuhr in diesem Issue mit statt als eigenes: eine Pflegeregel fuer ein Verzeichnis ohne Seiten ist eine Regel ueber nichts, und so war es ein Satz im selben Commit statt eines eigenen PATCH-Bumps.
Der Unterschied zu den drei bestehenden Dateien steht in der Klausel, sonst wuerde sie falsch gelesen:
README.md/EVALS.md/tools/README.mdspiegeln was der Stack ist und veralten bei jedem neuen Flag; einedocs/-Seite haelt einen Grund fest und veraltet nur, wenn eine aufgeschriebene Begruendung nicht mehr traegt. Geprueft wird das per Konstruktion nicht: kein normativer Satz, also nichts zu verifizieren, nur etwas zu pflegen.Akzeptanzkriterien
version-model.mdetwa schliesst mit "Where the procedure lives" aufinstructions/dev/version-parts.mdAGENTS.md§ Changelog umdocs/erweitert: welche Art Aenderung eine Hintergrundseite entwertet, und dass das per Konstruktion ungeprueft bleibt — Zeilen 279-284dist exporttraegt die Seiten in eine frische Instanz — belegt durch CI-Run 130 auf4e80a07(Schritt "The distribution works as a fresh instance"), nicht nur durch die Export-Zeile intools/CONTRACT.mdAGENTS.md-Klausel; die Prosa indocs/selbst begruendet keinen Bump — 4.3.0 → 4.3.1Verifikation
docs verify,instructions verifyund die Testsuite (869 Tests) laufen auf dem Stand dieses Commits gruen; CI-Runs 130 und 131 bestaetigen dasselbe inklusive dist-export-Replay gegen eine frische Instanz.Abhaengigkeit
Keine. #38 ist am 2026-09-03 gelandet (4.3.0);
status/blockedwar davor entfernt worden.Vorgeschichte
Abgespalten von #38 am 2026-09-03, als dessen Zuschnitt von "Entscheidungsseiten umziehen" auf "Hintergrund bekommt einen ausgelieferten Ort, Decision-Seiten bleiben in
kb/" korrigiert wurde. Am selben Tag, nach dem Landen von #38, um die Pflegefrage ergaenzt.Nachtrag 2026-09-03: Prozessfehler beim Abschluss, und was daraus folgte
Dieser Body wurde nach dem Schliessen auf den Endstand gebracht. Die Sitzung, die das Issue umgesetzt und geschlossen hat (Sonnet/medium, frische Sitzung mit
stack-dev), hatinstructions/dev/issue-tracking.mdSchritt 7 nicht befolgt und einen gruendlichen Abschlusskommentar ueber einem Body mit unangehakten Kriterien hinterlassen — derselbe Fehlermodus, den 4.1.2 (#44) eine Stunde zuvor benannt hatte.Ursache, ermittelt am Skill-Layer: nicht der Text der Regel, sondern ihre Erreichbarkeit. Die nummerierten Schritte von
stack-dev/SKILL.mdendeten bei "Verify before publishing"; ein Issue zu schliessen war ueberhaupt kein Schritt, sondern haengte an einem Zeiger innerhalb von Schritt 2 — einer Routing-Tabelle, keiner Checkliste. 4.1.2 hatteissue-tracking.mdum 101 Zeilen erweitert und im Skill nur den Blurb umformuliert, dessen fett gesetztes "not at the end" die Abschlusspflicht zusaetzlich verdeckte.Behoben in 4.3.2, Commit
56ecfc7: neuer nummerierter Schritt 5 im Skill ("Close the issue with a body rewrite, not a comment") mit dem Test inline, und der Schritt-2-Blurb rebalanciert. Begruendung in voller Laenge imCHANGES.md-Eintrag zu 4.3.2.Der Release-Drafter-Punkt, der in #42 zurueckgestellt war, hat seit demselben Tag ein eigenes Issue: #46.
Changelog: #38 ist gelandet (4.3.0, Commit
0b8ca74) —status/blockedentfernt, Abhaengigkeitsabschnitt entsprechend neu geschrieben. Ausgangslage praezisiert: das Verzeichnis existiert noch nicht im Arbeitsbaum, die erste hier geschriebene Seite legt es an.Neuer Abschnitt "Wer haelt
docs/aktuell": die Pflegefrage war nirgends hinterlegt.AGENTS.md§ Changelog nenntREADME.md/EVALS.md/tools/README.md, aber nichtdocs/. Entschieden, die Klausel dort und nur dort zu ergaenzen — nicht als wiederholte Anforderung pro Issue (zweite Kopie, Invariante 8; am Board prueft ohnehin nichts, sieheinstructions/dev/issue-tracking.md). Faehrt in diesem Issue mit statt als eigenes: eine Pflegeregel fuer ein Verzeichnis ohne Seiten ist eine Regel ueber nichts.Akzeptanzkriterien um die Klausel erweitert und um die Bump-Frage praezisiert: PATCH fuer die
AGENTS.md-Aenderung, diedocs/-Prosa selbst begruendet keinen Bump.Umgesetzt in 4.3.1 (Commit
4e80a07): vier Seiten indocs/, geschrieben von gezielt gebrieften Sub-Agents mit kontrolliertem Kontext (jeweils nur die relevanten Contracts/Instructions als Leseauftrag, keine Vorabkopie der Regeln in den Prompt).docs/pipeline-rationale.md- warumraw -> types/tools -> kb -> reportsvier getrennte Stufen sind, "never re-derive, always compile"docs/why-gates-are-code.md- warum Mass-Update-, Publish-Remote- und Iteration-Budget-Gate intools/wikitoolstatt in einer Instruktion stehendocs/ownership-and-templates.md- stack-eigene verbatim-Dateien vs. instanz-eigene.template-Dateiendocs/version-model.md- Kompatibilitaet vs. Migration als unabhaengige Fragen, illustriert an der 2.0.0-FallstudieAlle vier ohne normativen Satz, jede verlinkt auf das bindende Dokument statt dessen Regeln zu wiederholen - gegengeprueft beim Review vor dem Publish.
AGENTS.md§ Changelog um die Pflegeklausel ergaenzt (welche Art Aenderung einedocs/-Seite entwertet, und dass das per Konstruktion ungeprueft bleibt). Version-Bump PATCH (4.3.0 -> 4.3.1), da die Klausel Kontrollebene ist; diedocs/-Prosa selbst begruendet keinen Bump.dist exportin ein Scratch-Verzeichnis verifiziert: alle vier Seiten landen dort unveraendert.docs verify,instructions verifyund die volle Pytest-Suite (869 Tests) liefen gruen vor dem Publish.Alle Akzeptanzkriterien erfuellt, schliesse das Issue.
Changelog: Body nachträglich auf den Endstand gebracht — das Schließen am 17:41 hatte ihn als offene Arbeit stehen lassen.
Alle vier Seitenkandidaten und alle fünf Akzeptanzkriterien abgehakt, jeweils mit dem konkreten Beleg statt nur einem Haken (Dateipfade,
AGENTS.md-Zeilen 279-284, CI-Run 130 für das dist-export-Kriterium). Zukunftsform auf Vergangenheit umgestellt, wo das Issue umgesetzte Dinge noch als Vorhaben beschrieb — insbesondere die Pflegeklausel und die_copy_tree-Annahme, die sich bestätigt hat. Verifikationsabschnitt ergänzt. Nachtrag am Ende hält fest, warum der Body nachgezogen wurde.Issue bleibt geschlossen. Der Release-Drafter-Punkt aus #42 hat jetzt ein eigenes Issue: #46.