chemenu/DEVELOPMENT.md

Entwicklung dieses Stacks

Dieses Dokument richtet sich an Menschen, die an tools/wikitool, dem Type-Schema oder der Instruction-/Skill-Schicht selbst arbeiten - nicht an den Konsumenten einer Instanz. Für die Gegenseite (eine Instanz installieren, aktualisieren, betreiben) siehe INSTALL.md.

Diese Datei wird nicht ausgeliefert. Sie ist das menschliche Gegenstück zu instructions/dev/, das tools/wikitool dist export vollständig ausschließt: eine ausgelieferte Instanz hat keinen Release-Workflow, keine CI und kein Issue-Board, also braucht sie auch keine Anleitung dafür. dist_cmd.ROOT_FILES listet sie deshalb bewusst nicht - der Grund steht dort als Kommentar, damit eine spätere Sitzung die vermeintliche Lücke nicht "repariert". Und weil sie nicht ausgeliefert wird, darf sie - anders als README.md, INSTALL.md oder EVALS.md, die instructions verify auf genau diesen Punkt prüft - nach instructions/dev/ verlinken.

Der Release-Ablauf

Zwischen zwei Releases führt der Stack einen laufenden Versionskandidaten statt einer neuen Nummer pro Bump. Das volle Modell - Zustandsort, Eskalationslogik, warum eine Nummer erst durch ein Release verbraucht wird - steht in instructions/dev/version-parts.md und docs/version-model.md. Hier nur der Ablauf, in der Reihenfolge, in der eine Sitzung ihn tatsächlich durchläuft:

1. Bump eröffnet oder eskaliert den Kandidaten, gewichtet mit --impact.

   tools/wikitool version bump --minor --title "Was sich geändert hat" --impact medium
   

   Schreibt VERSION als X.Y.Z-beta.N und öffnet (oder aktualisiert) den passenden CHANGES.md-Eintrag. Mehrere Bumps für dieselbe Änderung sind normal - jeder aktualisiert denselben Eintrag, statt einen neuen zu eröffnen. --impact high|medium|low (Default medium) gruppiert den Eintrag; tools/wikitool version regrade korrigiert eine Note später, wenn der Gesamteindruck des Kandidaten den Blick auf einen früheren Bump ändert.

2. Der Eintrag bekommt seine Prosa - zweigeteilt. bump schreibt nur das Skelett (Heading, Datum, Autor, die maschinenverwaltete, gruppierte Bump-Titel-Liste, ggf. Breaking-/Migration-Zeile). Darunter kommen zwei Autorenanteile: eine kurze Zusammenfassung (ein paar Sätze, worum es in diesem Release geht) direkt unter der Liste, und darunter je Bump ein eigener ### <Bump-Titel>-Changeset-Absatz. Details dazu in instructions/dev/version-parts.md § The candidate model.

3. Verify laufen lassen, bevor irgendetwas gepublished wird:

   cd tools && .venv/bin/python -m pytest -q
   tools/wikitool docs verify
   tools/wikitool instructions verify
   

4. version release fixiert den Kandidaten, sobald er ausgeliefert werden soll:

   tools/wikitool version release --title "Zusammenfassender Titel"
   

   Streicht den -beta.N-Suffix aus VERSION und schließt den Changelog-Eintrag. --title ist optional - ohne ihn bleibt der Titel des letzten Bumps stehen; mit ihm bekommt ein Kandidat, der mehrere Bump-Titel gesammelt hat, eine zusammenfassende Überschrift. Verweigert, wenn der Kandidat zwei oder mehr Bumps gesammelt hat und die Zusammenfassung aus Schritt 2 noch fehlt - ein Kandidat mit genau einem Bump ist davon ausgenommen. Committet und pusht nichts (Invariante 5 in AGENTS.md).

5. Publish bewegt VERSION auf main.

   tools/wikitool publish --message "..."
   

   Das Mass-Update-Gate und das Publish-Remote-Gate gelten wie bei jedem anderen Publish - siehe instructions/gates.md.

6. CI übernimmt den Rest. .gitea/workflows/release.yml reagiert auf jeden Push, der VERSION bewegt: Eine suffixbehaftete VERSION (ein Kandidat) lässt den Job sauber überspringen, bevor er die Releases-API überhaupt anfragt - Betas werden nie veröffentlicht. Eine suffixfreie VERSION baut die Distribution (dist export), erzeugt Tag und Release und lädt Tarball plus Prüfsumme hoch. CI setzt den Tag, nie eine Sitzung - das hält Invariante 5 intakt.

Die drei Verify-Befehle stehen oben in Schritt 3; was jeder von ihnen prüft, steht in tools/CONTRACT.md und wird dort von docs verify gegen die tatsächliche CLI gehalten. Hier steht es bewusst nicht noch einmal: eine zweite Beschreibung derselben Befehle ist genau die Kopie, die driftet (AGENTS.md Invariante 8), und dieses Dokument liegt außerhalb der Dateien, die der Kommandotabellen-Check von docs verify abdeckt - hier fällt eine Drift also niemandem auf. Was pytest an dieser Stelle vom Entwickler erwartet, steht in instructions/dev/testing-conventions.md.

Die CI-Hälfte

.gitea/workflows/ci.yml läuft auf jeden Push/PR gegen main (Content-Pfade ausgenommen) und führt Testsuite, docs verify, instructions verify sowie einen vollständigen setup-instance.md-Replay gegen einen frischen dist export aus - derselbe Pfad, den ein neuer Nutzer tatsächlich geht. .gitea/workflows/nightly.yml ist der Drift-Check gegen die Zeit statt gegen einen Commit. .gitea/workflows/release.yml ist Schritt 6 oben.

Stack-Entwicklung als eigener Sitzungstyp

Der stack-dev-Skill (instructions/dev/, nur in diesem Ursprungs-Repo vorhanden) fasst die Regeln für eine Sitzung, die den Stack selbst statt Wiki-Inhalt bearbeitet: wann Quellenbindung nicht gilt, wo Design endet und die mechanische Phase beginnt (mit dem Modellwechsel-Hinweis), und endet mit dem Publish. Die Schlussphase - Issue-Body als Rewrite statt Kommentar, docs/-Veralterung, die Modell-Handover-Zeile über die ganze Sitzung - liegt seit 4.6.0 in einem eigenen Folge-Skill, stack-close, den stack-dev an dieser Stelle übergibt statt sie als weiteren eigenen Schritt zu führen. Siehe instructions/dev/issue-tracking.md für den Issue-Tracker selbst.