diff --git a/CHANGES.md b/CHANGES.md index 4c85cea..3a8e210 100644 --- a/CHANGES.md +++ b/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 + + +- issue-tracking - destructive-step invariants, comment-vs-body authority, rename sweep + + +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 diff --git a/VERSION b/VERSION index a84947d..4404a17 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.5.0 +4.5.1 diff --git a/instructions/dev/issue-tracking.md b/instructions/dev/issue-tracking.md index d06de47..4103b94 100644 --- a/instructions/dev/issue-tracking.md +++ b/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 -- + `" 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