torben/chemenu
1
1
Fork 0
Code Issues 25 Pull Requests Actions Packages Releases 34 Activity

Upgrade-Pfad hat keine agentengerichtete Prozedur: instructions/upgrade-instance.md (manual: true) #108

New Issue
Closed
opened 2026-09-16 11:54:03 +00:00 by torben · 1 comment
torben commented 2026-09-16 11:54:03 +00:00
Owner
Copy Link
Copy Source

Erledigt mit 504149c, Version 6.1.0-beta.1. Was gebaut wurde und was bewusst offen bleibt,
steht unten.

Das Problem, das es gab

Der Upgrade-Pfad einer ausgelieferten Instanz stand nur in INSTALL.md § "Eine Instanz
aktualisieren" - einem Dokument fuer Menschen. AGENTS.md § File naming fuehrt die
README-foermigen Wurzeldateien ausdruecklich als "never by an agent as instruction". Ausgefuehrt
wurde der Upgrade aber von einem Agenten, jedes Mal.

Beleg aus dem Lauf in #107 (Sitzung 671c1b9a, Prompt woertlich: "aktualisiere den stack auf
die letzte version."): der erste Tool-Call des Laufs listete instructions/ mit - der Agent
suchte zuerst eine Instruktion. Er fand keine, oeffnete instructions/private-instance.md (der
falsche Weg: Clone mit gemeinsamer History statt Tarball-Instanz), verwarf sie und griff auf
INSTALL.md zurueck. Drei Folgen im selben Lauf:

  1. migrate verify --from <commit vor dem Tausch> - INSTALL.md Schritt 6, erster Pruefschritt -
    lief in 33 Werkzeugaufrufen kein einziges Mal.
  2. Die Agent-Session wurde nie neu gestartet, obwohl AGENTS.md im selben Commit +44/-3 bekommen
    hatte; die optionale Migration lief anschliessend unter dem alten Kontrollplan.
  3. Drei Reihenfolgen waren im Umlauf - INSTALL.md Schritt 6, der Abschlussbericht von
    dist upgrade, und die tatsaechlich gelaufene. Der Lauf folgte der zweiten, was die erste zu
    toter Doku machte. Genau der Zustand, den Invariante 8 verbietet.

Was gebaut wurde

instructions/upgrade-instance.md, manual: true - dreizehn Schritte von der Sitzungs-Id bis
zum zweiten Publish. Die Tier-Wahl ist die aus instructions/CONTRACT.md § "Two forms, three
reference tiers": ein Skill wuerde seine description fuer eine Prozedur, die einmal pro Release
laeuft, in jede Sitzung legen; ein Linked-Tier waere ein Angebot, einen 69-Dateien-Lauf beilaeufig
aufzugreifen. Manual braucht keine Referenz und verbietet nur Links aus AGENTS.md/CLAUDE.md/einem
Skill - Erwaehnungen in tools/CONTRACT.md und INSTALL.md sind zulaessig.

Entschieden und umgesetzt, was der Entwurf offengelassen hatte:

  • Der Sitzungsneustart faellt nach dem Publish der Maschinerie und vor die Migrationskette -
    nicht ans Ende, wie beide alten Reihenfolgen es sagten. Dort faengt der neue Kontrollplan an zu
    gelten, und genau dort hat der beobachtete Lauf ihn nicht gehabt. migrate status ist der
    Wiedereinstiegspunkt der neuen Sitzung, weil es zustandsbehaftet ist und keine Uebergabe
    braucht.
  • Die Maschinerie wird vor der Kette publiziert. Der Zwischenzustand ist einer, den der Stack
    benennt statt vermeidet (.wikitool-kb.json), und er haelt einen 200-Dateien-Tausch aus
    demselben Commit wie eine Inhaltsumschreibung heraus.
  • Auffindbarkeit ueber den Abschlussbericht von dist upgrade, der statt einer eigenen
    Schrittliste die Datei nennt und das Kommando, bei dem der Lauf weitergeht
    (instructions sync) - ein Zeiger statt einer dritten Kopie. Der Bericht nennt bewusst keine
    Schrittnummer: die wandert, der Kommandoname nicht.

Zwei Schritte sagen ausdruecklich, dass sie eine Werkzeugluecke umgehen, und was sie ueberfluessig
macht - in Worten, ohne Issue-Nummer, weil die Datei ausgeliefert wird:

  • Schritt 2 liest die Release-Notes von der Release-Seite statt mit version notes ( Upgrade-Lauf 5.0.0 -> 6.0.0 auf ausgelieferter Instanz: Laufbericht, Telemetrie, sieben Befunde (#107)
    Befund 2).
  • Schritt 6 nimmt die Release-Fassung einer lokal veraenderten stackeigenen Datei von Hand (#107
    Befund 3) - und der noetige Commit geht ueber publish --no-push, nicht ueber git commit.
    Das ist im Review nachgetragen worden: der beobachtete Lauf hat fuer die Handreparatur
    (7fe8353) ein rohes git commit abgesetzt und damit Invariante 5 verletzt, um die
    Sauberkeits-Vorbedingung des naechsten Kommandos herzustellen. Eine Werkzeugluecke hat dort eine
    in Code gegossene Regel gebrochen, und nichts hat es gemeldet.

Mitgenommen, ausserhalb des urspruenglichen Schnitts:

  • instructions/session-setup.md sagt jetzt, dass ein export nur traegt, solange die Shell
    traegt, nennt die Inline-Form pro Aufruf und den Einzeiler, mit dem sich beantworten laesst,
    welcher Fall vorliegt. Das gehoerte dorthin und nicht in die neue Instruktion (Invariante 8) und
    hakt zugleich ein Akzeptanzkriterium aus #107 Befund 1 ab.
  • INSTALL.md § "Version und Updates" sagt jetzt bei version notes dazu, dass der Befehl nur dort
    antwortet, wo eine gefuellte CHANGES.md liegt. Das nimmt der Entscheidung in #107 Befund 2
    (Feed-Fallback vs. Doku) nichts vorweg, beendet aber einen falschen Satz in einem Dokument, das
    in derselben Sitzung ohnehin umgebaut wurde.

Akzeptanzkriterien

  • instructions/upgrade-instance.md existiert mit manual: true;
    tools/wikitool instructions verify gruen (23 Instruktionen, 7 Skills, 14 publizierte
    Kopien deckungsgleich) - also kein Link aus AGENTS.md, CLAUDE.md oder einem Skill.
  • tools/wikitool docs verify gruen, einschliesslich check_no_issue_references ueber 73
    ausgelieferte Dokumente und Linkaufloesung ueber 58 Referenzdateien.
  • INSTALL.md § "Eine Instanz aktualisieren" traegt die Schrittfolge nicht mehr: die Schritte
    1 bis 6 sind weg, geblieben ist die Entscheidung davor und ein Verweis.
    Mit einer benannten Ausnahme, die das Kriterium woertlich nicht erfuellt und die so
    gewollt ist: der Block zum ersten Sprung auf 4.5.0 nennt dist upgrade --dry-run, das die
    Instruktion ebenfalls nennt. Er steht dort, weil in einer Instanz vor 4.5.0 weder das
    Kommando noch die Instruktion existiert - ein Fall, den die Instruktion konstruktionsbedingt
    nicht abdecken kann.
  • Der Abschlussbericht von dist upgrade nennt den Dateinamen der Instruktion;
    test_closing_report_points_at_the_upgrade_instruction in
    tools/chemenu/tests/test_dist_upgrade.py prueft Dateiname und
    Wiedereinstiegskommando.
  • Die Instruktion nennt migrate verify --from <commit> (Schritt 13, gegen den in Schritt 7
    notierten Commit) und den Neustart der Agent-Session (Schritt 11), jeweils an der Stelle, an
    der der Schritt faellt.
  • Kein release-spezifischer Schritt: die Instruktion nennt keine Version ausser als Platzhalter
    und verweist fuer alles Sprungspezifische auf die Release-Notes und die Migrationsdokumente
    im Tarball. Der Constraint steht im Kopf der Datei, damit die naechste Aenderung ihn nicht
    unwissentlich bricht.
  • Jeder Workaround-Schritt nennt die Bedingung seines Wegfalls in Worten, ohne Issue-Nummer.
  • tools/wikitool version bump --minor -> 6.1.0-beta.1 mit ausgeschriebenem
    Changelog-Eintrag; pytest 1276 gruen (einer neu), docs verify und instructions verify
    gruen.

Was offen bleibt - bewusst

Die Instruktion ersetzt keinen der Werkzeugdefekte, sie fuehrt um sie herum. Offen in #107 und
weiterhin dort zu entscheiden:

  • Befund 2, version notes auf einer Instanz: Feed-Fallback oder Doku-Aenderung.
  • Befund 3, ein Gegenstueck zu --keep-local. Der Review hat das Argument dafuer verschaerft:
    ohne das Flag kostet der Fall nicht nur drei Handgriffe, er hat im beobachteten Lauf eine
    Invariantenverletzung produziert.
  • Befund 1, die Session-Id-Zersplitterung. Hier ist nur die Anleitung repariert, nicht die
    Fallback-Kette und nicht der Join-Key der Telemetrie.

Verschwindet einer dieser Defekte, verschwindet der zugehoerige Schritt aus der Instruktion - beide
sagen selbst, wann.

Herkunft

Abgeleitet aus dem Review des Upgrade-Laufs in #107 (Review-Sitzung 2026-09-16), dort als Befund 7
gefuehrt. Gebaut, geprueft und publiziert in derselben Sitzung.

**Erledigt** mit `504149c`, Version `6.1.0-beta.1`. Was gebaut wurde und was bewusst offen bleibt, steht unten. ## Das Problem, das es gab Der Upgrade-Pfad einer ausgelieferten Instanz stand nur in INSTALL.md § "Eine Instanz aktualisieren" - einem Dokument fuer Menschen. `AGENTS.md` § File naming fuehrt die README-foermigen Wurzeldateien ausdruecklich als *"never by an agent as instruction"*. Ausgefuehrt wurde der Upgrade aber von einem Agenten, jedes Mal. Beleg aus dem Lauf in #107 (Sitzung `671c1b9a`, Prompt woertlich: *"aktualisiere den stack auf die letzte version."*): der erste Tool-Call des Laufs listete `instructions/` mit - der Agent suchte zuerst eine Instruktion. Er fand keine, oeffnete `instructions/private-instance.md` (der falsche Weg: Clone mit gemeinsamer History statt Tarball-Instanz), verwarf sie und griff auf INSTALL.md zurueck. Drei Folgen im selben Lauf: 1. `migrate verify --from <commit vor dem Tausch>` - INSTALL.md Schritt 6, erster Pruefschritt - lief in 33 Werkzeugaufrufen kein einziges Mal. 2. Die Agent-Session wurde nie neu gestartet, obwohl `AGENTS.md` im selben Commit +44/-3 bekommen hatte; die optionale Migration lief anschliessend unter dem alten Kontrollplan. 3. Drei Reihenfolgen waren im Umlauf - INSTALL.md Schritt 6, der Abschlussbericht von `dist upgrade`, und die tatsaechlich gelaufene. Der Lauf folgte der zweiten, was die erste zu toter Doku machte. Genau der Zustand, den Invariante 8 verbietet. ## Was gebaut wurde **`instructions/upgrade-instance.md`, `manual: true`** - dreizehn Schritte von der Sitzungs-Id bis zum zweiten Publish. Die Tier-Wahl ist die aus `instructions/CONTRACT.md` § "Two forms, three reference tiers": ein Skill wuerde seine `description` fuer eine Prozedur, die einmal pro Release laeuft, in jede Sitzung legen; ein Linked-Tier waere ein Angebot, einen 69-Dateien-Lauf beilaeufig aufzugreifen. Manual braucht keine Referenz und verbietet nur Links aus AGENTS.md/CLAUDE.md/einem Skill - Erwaehnungen in `tools/CONTRACT.md` und INSTALL.md sind zulaessig. Entschieden und umgesetzt, was der Entwurf offengelassen hatte: - **Der Sitzungsneustart faellt nach dem Publish der Maschinerie und vor die Migrationskette** - nicht ans Ende, wie beide alten Reihenfolgen es sagten. Dort faengt der neue Kontrollplan an zu gelten, und genau dort hat der beobachtete Lauf ihn nicht gehabt. `migrate status` ist der Wiedereinstiegspunkt der neuen Sitzung, weil es zustandsbehaftet ist und keine Uebergabe braucht. - **Die Maschinerie wird vor der Kette publiziert.** Der Zwischenzustand ist einer, den der Stack benennt statt vermeidet (`.wikitool-kb.json`), und er haelt einen 200-Dateien-Tausch aus demselben Commit wie eine Inhaltsumschreibung heraus. - **Auffindbarkeit ueber den Abschlussbericht von `dist upgrade`**, der statt einer eigenen Schrittliste die Datei nennt und das Kommando, bei dem der Lauf weitergeht (`instructions sync`) - ein Zeiger statt einer dritten Kopie. Der Bericht nennt bewusst keine Schrittnummer: die wandert, der Kommandoname nicht. Zwei Schritte sagen ausdruecklich, dass sie eine Werkzeugluecke umgehen, und was sie ueberfluessig macht - in Worten, ohne Issue-Nummer, weil die Datei ausgeliefert wird: - Schritt 2 liest die Release-Notes von der Release-Seite statt mit `version notes` (#107 Befund 2). - Schritt 6 nimmt die Release-Fassung einer lokal veraenderten stackeigenen Datei von Hand (#107 Befund 3) - **und der noetige Commit geht ueber `publish --no-push`, nicht ueber `git commit`**. Das ist im Review nachgetragen worden: der beobachtete Lauf hat fuer die Handreparatur (`7fe8353`) ein rohes `git commit` abgesetzt und damit Invariante 5 verletzt, um die Sauberkeits-Vorbedingung des naechsten Kommandos herzustellen. Eine Werkzeugluecke hat dort eine in Code gegossene Regel gebrochen, und nichts hat es gemeldet. **Mitgenommen, ausserhalb des urspruenglichen Schnitts:** - `instructions/session-setup.md` sagt jetzt, dass ein `export` nur traegt, solange die Shell traegt, nennt die Inline-Form pro Aufruf und den Einzeiler, mit dem sich beantworten laesst, welcher Fall vorliegt. Das gehoerte dorthin und nicht in die neue Instruktion (Invariante 8) und hakt zugleich ein Akzeptanzkriterium aus #107 Befund 1 ab. - INSTALL.md § "Version und Updates" sagt jetzt bei `version notes` dazu, dass der Befehl nur dort antwortet, wo eine gefuellte `CHANGES.md` liegt. Das nimmt der Entscheidung in #107 Befund 2 (Feed-Fallback vs. Doku) nichts vorweg, beendet aber einen falschen Satz in einem Dokument, das in derselben Sitzung ohnehin umgebaut wurde. ## Akzeptanzkriterien - [x] `instructions/upgrade-instance.md` existiert mit `manual: true`; `tools/wikitool instructions verify` gruen (23 Instruktionen, 7 Skills, 14 publizierte Kopien deckungsgleich) - also kein Link aus AGENTS.md, CLAUDE.md oder einem Skill. - [x] `tools/wikitool docs verify` gruen, einschliesslich `check_no_issue_references` ueber 73 ausgelieferte Dokumente und Linkaufloesung ueber 58 Referenzdateien. - [x] INSTALL.md § "Eine Instanz aktualisieren" traegt die Schrittfolge nicht mehr: die Schritte 1 bis 6 sind weg, geblieben ist die Entscheidung davor und ein Verweis. **Mit einer benannten Ausnahme**, die das Kriterium woertlich nicht erfuellt und die so gewollt ist: der Block zum ersten Sprung auf `4.5.0` nennt `dist upgrade --dry-run`, das die Instruktion ebenfalls nennt. Er steht dort, weil in einer Instanz vor `4.5.0` weder das Kommando noch die Instruktion existiert - ein Fall, den die Instruktion konstruktionsbedingt nicht abdecken kann. - [x] Der Abschlussbericht von `dist upgrade` nennt den Dateinamen der Instruktion; `test_closing_report_points_at_the_upgrade_instruction` in `tools/chemenu/tests/test_dist_upgrade.py` prueft Dateiname **und** Wiedereinstiegskommando. - [x] Die Instruktion nennt `migrate verify --from <commit>` (Schritt 13, gegen den in Schritt 7 notierten Commit) und den Neustart der Agent-Session (Schritt 11), jeweils an der Stelle, an der der Schritt faellt. - [x] Kein release-spezifischer Schritt: die Instruktion nennt keine Version ausser als Platzhalter und verweist fuer alles Sprungspezifische auf die Release-Notes und die Migrationsdokumente im Tarball. Der Constraint steht im Kopf der Datei, damit die naechste Aenderung ihn nicht unwissentlich bricht. - [x] Jeder Workaround-Schritt nennt die Bedingung seines Wegfalls in Worten, ohne Issue-Nummer. - [x] `tools/wikitool version bump --minor` -> `6.1.0-beta.1` mit ausgeschriebenem Changelog-Eintrag; `pytest` 1276 gruen (einer neu), `docs verify` und `instructions verify` gruen. ## Was offen bleibt - bewusst Die Instruktion ersetzt keinen der Werkzeugdefekte, sie fuehrt um sie herum. Offen in #107 und weiterhin dort zu entscheiden: - **Befund 2**, `version notes` auf einer Instanz: Feed-Fallback oder Doku-Aenderung. - **Befund 3**, ein Gegenstueck zu `--keep-local`. Der Review hat das Argument dafuer verschaerft: ohne das Flag kostet der Fall nicht nur drei Handgriffe, er hat im beobachteten Lauf eine Invariantenverletzung produziert. - **Befund 1**, die Session-Id-Zersplitterung. Hier ist nur die Anleitung repariert, nicht die Fallback-Kette und nicht der Join-Key der Telemetrie. Verschwindet einer dieser Defekte, verschwindet der zugehoerige Schritt aus der Instruktion - beide sagen selbst, wann. ## Herkunft Abgeleitet aus dem Review des Upgrade-Laufs in #107 (Review-Sitzung 2026-09-16), dort als Befund 7 gefuehrt. Gebaut, geprueft und publiziert in derselben Sitzung.
torben added the prio/plannedsize/Marea/distributionkind/build labels 2026-09-16 11:54:03 +00:00
torben commented 2026-09-16 12:07:37 +00:00
Author
Owner
Copy Link
Copy Source

Changelog: Geschlossen mit 504149c (6.1.0-beta.1). Body auf den Endstand geschrieben: alle acht Akzeptanzkriterien abgehakt, eines davon mit benannter Ausnahme (der 4.5.0-Sonderfall in INSTALL.md nennt weiterhin dist upgrade --dry-run, weil dort weder Kommando noch Instruktion existieren). Aus dem Entwurf entschieden: Sitzungsneustart zwischen Maschinerie-Publish und Migrationskette statt am Ende, migrate status als Wiedereinstiegspunkt, Abschlussbericht nennt Datei plus Wiedereinstiegskommando statt einer Schrittnummer. Zwei Dinge ausserhalb des Schnitts mitgenommen: die Inline-Form in instructions/session-setup.md (hakt ein Kriterium aus #107 Befund 1 ab) und die version notes-Einschraenkung in INSTALL.md. Im Review nachgetragen und in Schritt 6 der Instruktion verarbeitet: der beobachtete Lauf hat fuer die Handreparatur ein rohes git commit abgesetzt - Invariante 5 - um die Sauberkeits-Vorbedingung herzustellen.

**Changelog:** Geschlossen mit `504149c` (`6.1.0-beta.1`). Body auf den Endstand geschrieben: alle acht Akzeptanzkriterien abgehakt, eines davon mit benannter Ausnahme (der `4.5.0`-Sonderfall in INSTALL.md nennt weiterhin `dist upgrade --dry-run`, weil dort weder Kommando noch Instruktion existieren). Aus dem Entwurf entschieden: Sitzungsneustart zwischen Maschinerie-Publish und Migrationskette statt am Ende, `migrate status` als Wiedereinstiegspunkt, Abschlussbericht nennt Datei plus Wiedereinstiegskommando statt einer Schrittnummer. Zwei Dinge ausserhalb des Schnitts mitgenommen: die Inline-Form in `instructions/session-setup.md` (hakt ein Kriterium aus #107 Befund 1 ab) und die `version notes`-Einschraenkung in INSTALL.md. Im Review nachgetragen und in Schritt 6 der Instruktion verarbeitet: der beobachtete Lauf hat fuer die Handreparatur ein rohes `git commit` abgesetzt - Invariante 5 - um die Sauberkeits-Vorbedingung herzustellen.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No Label area/distribution kind/build prio/planned size/M
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#108
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?