instructions/dev/issue-tracking.md: destructive-step invariants, comment-vs-body authority, rename sweep (#47 Block 1, #29)

Files changed:
- CHANGES.md
- VERSION
- instructions/dev/issue-tracking.md

CHANGES.md

@@ -35,6 +35,56 @@ dev-checkout concern - readable here, never shipped as something to parse.
 
 ---
 
+## 4.5.1 - 2026-09-04 - issue-tracking - destructive-step invariants, comment-vs-body authority, rename sweep
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- issue-tracking - destructive-step invariants, comment-vs-body authority, rename sweep
+<!-- /wikitool:bumps -->
+
+Block 1 aus #47 (gemeinsam mit #29): drei Ergänzungen an
+`instructions/dev/issue-tracking.md`, ausgelöst durch zwei Fehlerklassen, die
+in derselben Sitzung am Stack aufgetreten waren.
+
+- **Schritt 1** trägt jetzt, dass destruktive Schritte im Body die Invariante
+  nennen müssen, die sie nicht verletzen dürfen, und dass ein
+  Akzeptanzkriterium eine prüfbare Eigenschaft ist, keine Tätigkeit. Auslöser
+  war #30: der Body schrieb wörtlich "Arbeitsverzeichnis entfernen" für den
+  `upstream merge`-Ablauf, und genau das wurde zum datenvernichtenden Bug -
+  ein `shutil.rmtree` auf eine Stage mit gitignorierten, nicht
+  rekonstruierbaren Daten.
+- **Schritt 2** trägt jetzt die Lesesicht auf Body und Kommentare, die es
+  bisher nur aus Autorensicht gab: der Body ist der Stand, Kommentare sind
+  Historie; ein erkennbar veralteter Body wird richtiggestellt statt
+  umgangen; widersprüchliche Kommentare werden nach Beleg aufgelöst, nicht
+  nach Datum. Auslöser war ebenfalls #30 (ein Kommentar empfahl das Gegenteil
+  dessen, was der Body später festlegte) und #10 (ein seit Tagen veralteter
+  Body gegen drei widersprechende Kommentare, zwei davon sich selbst
+  widersprechend).
+- Neuer Abschnitt **"Renames and other decay in the tracker"** nach Schritt 7:
+  ein Rename ist erst fertig, wenn auch die offenen Issues nachgezogen sind,
+  weil `wikitool` diesen Tracker nicht kennt und nicht kennenlernen soll. Mit
+  der Wegweiser-vs-Beleg-Unterscheidung aus #29 und dem Hinweis, dass auch
+  verschwundene `kb/`-Seiten und private Infrastrukturangaben Issue-Texte
+  altern lassen. Ein neuer Trigger in "When to run" verweist darauf.
+
+Keine der drei Ergänzungen verschiebt die bestehende Nummerierung der
+Schritte 1-7 - die Querverweise darauf (u. a. aus
+`instructions/dev/stack-dev/SKILL.md` auf Schritt 7, aus
+`kb/concepts/Issue Label Scheme.md` auf Schritt 2) bleiben also gültig, ohne
+angefasst zu werden.
+
+Verifiziert: `tools/wikitool instructions verify`, `tools/wikitool docs
+verify`, beide grün (Prosa-only, kein Interface geändert, PATCH).
+
+#47 bleibt offen (Block 2: der Skill-Schnitt aus Vorschlag E; Block 3: die
+beiden Nebenbefunde). #29 bleibt ebenfalls offen: dieser Block deckte nur den
+Regelabsatz, nicht den noch ausstehenden Pfad-Durchgang durch #4, #5, #15,
+#21, #16, #26 - der war nicht Teil des Auftrags für diesen Block.
+
+---
+
 ## 4.5.0 - 2026-09-04 - Beide Update-Wege in Code: upstream merge fuer Clones, dist upgrade fuer Tarball-Instanzen
 
 **Author:** Torben Nehmer

INSTALL.md

@@ -195,6 +195,20 @@ dem sich jede Instanz mitten im Upgrade befindet.
    tools/wikitool dist upgrade <tarball-oder-verzeichnis> --dry-run
    ```
 
+   **Beim ersten Sprung auf `4.5.0` oder höher gibt es dieses Kommando in der Instanz noch
+   nicht** - es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball
+   verwenden, gegen die alte Instanz gerichtet:
+
+   ```bash
+   tar -xzf chemenu-stack-<version>.tar.gz
+   CHEMENU_ROOT="$PWD" chemenu-stack-<version>/tools/wikitool \
+     dist upgrade chemenu-stack-<version>.tar.gz --dry-run
+   ```
+
+   `CHEMENU_ROOT` sagt dem Paket, auf welchen Korpus es zeigen soll (siehe § Konfiguration);
+   ohne die Variable würde es den entpackten Tarball selbst für die Instanz halten. Ab dem
+   zweiten Upgrade trägt die Instanz das Kommando selbst und die kurze Form oben genügt.
+
    Klassifiziert jede Datei aus dem `files`-Block der neuen `.wikitool-release.json`:
    unverändert seit der Installation, lokal verändert oder gelöscht, neu im Release, oder aus dem
    Release entfallen - und druckt die Migrationskette, die nach dem Tausch aussteht, ohne sie

VERSION

@@ -1 +1 @@
-4.5.0
+4.5.1

instructions/dev/issue-tracking.md

@@ -34,6 +34,8 @@ issues at that URL, which is exactly why `dist export` excludes
   moved.
 - Closing one: the body is rewritten to its final state first, and only then
   closed (step 7).
+- A rename or move ships: sweep the open issues for text that assumed the old
+  name or path (§ Renames and other decay in the tracker).
 
 ## Steps
 
@@ -42,6 +44,26 @@ issues at that URL, which is exactly why `dist export` excludes
    specific files or commands involved. An issue that only makes sense to
    whoever wrote it is a note, and notes were the problem.
 
+   **Destructive steps carry the invariant they must not violate.** A body
+   that prescribes a mechanism gets built as prescribed - including its
+   bugs. Where a step deletes, overwrites, resets or moves, name the
+   property that must still hold afterwards, not only the command that gets
+   there. "Remove the working directory, then `git checkout HEAD --
+   <stage>`" is a mechanism; "the content stages must afterwards match
+   `HEAD` exactly, without any untracked or ignored file being touched" is
+   the same instruction plus its test - a build instruction and an
+   acceptance criterion at once, so the defect surfaces while the test is
+   written rather than in review afterwards. #30's `upstream merge` body
+   wrote the mechanism and got exactly that bug: a working-directory removal
+   that took a stage's gitignored, unrecoverable data with it.
+
+   **An acceptance criterion states a checkable property, not an activity.**
+   "Implement X" is done when someone says so; "after `upstream merge`,
+   `reports/` still holds every file it held before" is done when it is
+   true. This is not a ban on imperative steps - a numbered procedure can
+   still produce a correct control flow, and that is its merit - it binds
+   the destructive steps, and every box in the criteria list.
+
 2. **The body is the working state, not a historical first post - keep it
    current as you go.** It is this stack's plan file: the same thing a harness's
    own plan document is, and it is maintained the same way. Not written once,
@@ -73,6 +95,32 @@ issues at that URL, which is exactly why `dist export` excludes
    Body rewrites and comments are an LLM session's job. A human normally
    touches only labels and metadata directly.
 
+   **Reading an issue, the body is the state and comments are history.** A
+   session picking an issue up reads the body as the spec; comments are read
+   for provenance - why something was decided, what was tried - never as
+   the current instruction. A recommendation in a comment can be older than
+   the body's decision and read just as convincingly: on #30 an earlier
+   comment recommended a smaller, `verify`-only command, while the body had
+   since settled on building the full `merge` command. A session trusting
+   the comment would have built the wrong thing, with a plausible
+   justification out of this repo's own tracker.
+
+   **A body that is demonstrably wrong is corrected first, not worked
+   around.** "Body beats comment" is a rule of precedence, not a licence to
+   execute a stale spec. Where a comment or the tree proves a claim in the
+   body false, the body is rewritten before the work starts - the rewrite
+   above is the fix; leaning on the comments as the "real" state is not.
+   #10 is the case: its body claimed coverage had never been measured while
+   three comments carried a percentage, a statement count and a CI run
+   number.
+
+   **Where two comments contradict each other, evidence decides, not
+   recency.** On #10, one comment showed a retrieved artifact with zero
+   items on a finished run - the report was not actually retrievable - and
+   a later comment declared the same criterion met without re-checking. The
+   later comment is not the newer truth, only the unchecked one. Resolve it
+   into the body with the evidence named, or mark the point open.
+
 3. **Comment a changelog, never a copy.** A body rewrite gets one short comment
    naming only what changed against the previous state - what is new, what is
    gone, what was corrected. Do not snapshot the old body into a comment: a full
@@ -180,6 +228,27 @@ issues at that URL, which is exactly why `dist export` excludes
    shipped. Nothing mechanical catches it (see below), which is why it is a step
    rather than a habit.
 
+## Renames and other decay in the tracker
+
+A rename is not finished when the tree is green. Renaming a package, a path,
+a command, a flag or the repository itself moves text that lives outside the
+working tree, and the open issues are the largest such text. Nothing catches
+them - `wikitool` does not know this tracker exists and must not learn (see
+"What no tool checks" below) - so a pass over the open issues is part of the
+rename, in the session that did it, not a follow-up someone remembers.
+
+Distinguish a wayfinder from a piece of evidence: a path meant to point at
+where something *is* gets pulled through; a path quoted for what was true at
+a time is left standing and dated. Note per corrected body what was pulled
+through and when, so the next pass can tell a checked body from one that
+merely looks right. Closed issues are out of scope - they guide nobody.
+
+Renames are not the only thing that ages an issue text. A page a body cites
+can vanish from `kb/` (`wikitool search` against the cited titles is the
+second pass), and an old body can carry private infrastructure detail into
+what is now a public tracker - both found in the same issue, both worth the
+same look.
+
 ## What no tool checks
 
 `wikitool` does not know this tracker exists, and should not learn. It ships to