docs/ befuellen: Stack-Hintergrund fuer jede Instanz, die ueber den Basisbetrieb hinaus will #45
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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.