# 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](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](instructions/dev/version-parts.md) und
[docs/version-model.md](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.**

   ```bash
   tools/wikitool version bump --minor --title "Was sich geändert hat"
   ```

   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.

2. **Der Eintrag bekommt seine Prosa.** `bump` schreibt nur das Skelett (Heading, Datum, Autor,
   die maschinenverwaltete Bump-Titel-Liste, ggf. Breaking-/Migration-Zeile). Der Fließtext
   darunter ist Autorenarbeit, wie bei `new` und der Seiten-Prosa.

3. **Verify laufen lassen, bevor irgendetwas gepublished wird:**

   ```bash
   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:

   ```bash
   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. Committet und pusht
   nichts (Invariante 5 in [AGENTS.md](AGENTS.md)).

5. **Publish bewegt `VERSION` auf `main`.**

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

   Das Mass-Update-Gate und das Publish-Remote-Gate gelten wie bei jedem anderen Publish -
   siehe [instructions/gates.md](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](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](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](instructions/dev/issue-tracking.md) für den
Issue-Tracker selbst.