stack: Upgrade-Pfad bekommt eine eigene manual-Instruktion, INSTALL.md verweist darauf (#108)

Files changed:
- CHANGES.md
- INSTALL.md
- VERSION
- instructions/session-setup.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/tests/test_dist_upgrade.py

CHANGES.md

@@ -59,6 +59,70 @@ concern - readable here, never shipped as something to parse.
 
 ---
 
+## 6.1.0-beta.1 - 2026-09-16 - Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
+<!-- /wikitool:bumps -->
+
+### Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
+
+Der Upgrade-Pfad einer ausgelieferten Instanz stand nur in INSTALL.md § "Eine Instanz
+aktualisieren" - einem Dokument fuer Menschen, das `AGENTS.md` § File naming ausdruecklich als
+*"never by an agent as instruction"* fuehrt. Ausgefuehrt wird er aber von einer Agent-Sitzung,
+jedes Mal. Der getracete 5.0.0-auf-6.0.0-Lauf auf einer echten Instanz zeigt, was daraus folgt:
+der erste Tool-Call listete `instructions/` mit, fand keine passende Instruktion, oeffnete die
+naechstliegende (`private-instance.md`, der falsche der beiden Wege) und fiel dann auf INSTALL.md
+zurueck. `migrate verify --from <commit vor dem Tausch>` - INSTALL.md Schritt 6, erster
+Pruefschritt - lief in 33 Werkzeugaufrufen kein einziges Mal, und die Agent-Sitzung wurde nie neu
+gestartet, obwohl `AGENTS.md` im selben Commit +44/-3 bekommen hatte. Die anschliessende Migration
+lief damit unter dem alten Kontrollplan.
+
+Dahinter lagen drei Reihenfolgen nebeneinander: die in INSTALL.md, die im Abschlussbericht von
+`dist upgrade`, und die tatsaechlich gelaufene. Genau der Zustand, den Invariante 8 verbietet.
+
+`instructions/upgrade-instance.md` ist jetzt die eine Fassung: dreizehn Schritte von der
+Sitzungs-Id bis zum zweiten Publish, mit dem Sitzungsneustart an der Stelle, an der der neue
+Kontrollplan zu gelten anfaengt - nach dem Publish der Maschinerie, vor der Migrationskette, und
+mit `migrate status` als Wiedereinstiegspunkt fuer die neue Sitzung. `manual: true`, weil die
+Prozedur einmal pro Release laeuft und nie implizit aufgegriffen werden darf; ein Skill wuerde
+seine `description` dafuer in jede Sitzung legen. Auffindbar ist sie ueber den Abschlussbericht
+von `dist upgrade`, der statt einer eigenen Schrittliste jetzt die Datei nennt und das Kommando,
+bei dem der Lauf weitergeht (`instructions sync`). INSTALL.md behaelt, was ein Mensch *vorher*
+entscheidet, und den einen Sonderfall, den die Instruktion nicht abdecken kann, weil es sie dort
+noch nicht gibt: den ersten Sprung auf `4.5.0`.
+
+Zwei Schritte der Instruktion sagen ausdruecklich, dass sie eine Luecke umgehen, und was sie
+ueberfluessig macht. Schritt 2 liest die Release-Notes von der Release-Seite statt mit
+`version notes`, weil eine Instanz ihre `CHANGES.md` als Stub bekommt und `dist upgrade` sie nie
+ueberschreibt - der Befehl kann dort nicht heute und nicht spaeter antworten. Schritt 6 nimmt fuer
+eine lokal veraenderte stackeigene Datei die Release-Fassung von Hand, weil es zu `--keep-local`
+kein Gegenstueck gibt; dabei geht der noetige Commit ueber `publish --no-push`, nicht ueber
+`git commit` - Invariante 5 kennt keine Ausnahme fuer "ist ja nur eine Vorbedingung", und genau
+diese Ausnahme hat sich der beobachtete Lauf genommen.
+
+`instructions/session-setup.md` sagt jetzt, dass ein `export` nur traegt, solange die Shell
+traegt. Mehrere Harnesses starten pro Tool-Call eine frische Shell - das Arbeitsverzeichnis
+ueberlebt, Shell-State nicht - und dann faellt jeder Aufruf auf seine eigene Parent-PID zurueck.
+Im gemessenen Lauf wurde eine Sitzung so zu 21 Telemetrie-Buckets mit hoechstens drei Aufrufen
+pro Bucket: das Iteration-Budget-Gate (60) und der Loop-Breaker (3 identische in Folge) konnten
+strukturell nicht ausloesen. Die Anleitung nennt deshalb die Inline-Form pro Aufruf und den
+Einzeiler, mit dem sich beantworten laesst, welcher Fall vorliegt.
+
+Verifiziert: `docs verify` (73 ausgelieferte Dokumente, 58 Referenzdateien),
+`instructions verify` (23 Instruktionen, 7 Skills) und 1276 Tests gruen - einer davon neu und auf
+genau die Stelle gerichtet, an der die Doppelung wieder entstehen wuerde: der Abschlussbericht
+von `dist upgrade` muss die Instruktion und ihr Wiedereinstiegskommando nennen, nicht eine zweite
+Kopie der Liste.
+
+Kein Grenzuebertritt: eine neue Instruktionsdatei und ein geaenderter Meldungstext sind in beide
+Richtungen ein Drop-in. Eine Instanz, die zurueckgeht, behaelt die Datei als ueberzaehlige Datei,
+und nichts liest sie automatisch - `manual: true` heisst genau das.
+
+---
+
 ## 6.0.1 - 2026-09-16 - docs toc/verify erreichen die .template-Form einer Referenzdatei
 
 **Author:** Torben Nehmer