stack: Changelog-Eintrag geschichtet - Impact-Gruppierung, version regrade, Zusammenfassungspflicht (schliesst #95)

Files changed:
- CHANGES.md
- DEVELOPMENT.md
- VERSION
- instructions/dev/stack-dev/SKILL.md
- instructions/dev/version-parts.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/run_budget.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/tests/test_run_budget.py
- tools/chemenu/tests/test_version_cmd.py
- tools/chemenu/version.py

instructions/dev/version-parts.md

@@ -55,10 +55,32 @@ a new one, and only `version release` turns it into something the release workfl
   its parser never has to know the suffix exists.
 - **One `CHANGES.md` entry per candidate**, not per bump. The first bump of a candidate opens it
   (heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list seeded with that
-  bump's `--title`); every later bump of the *same* candidate updates that entry in place -
-  heading, date and the bumps list all move, but the entry's own prose (written below the
-  skeleton, by hand) is left alone. `version notes` therefore still prints exactly one entry per
-  release, whatever a candidate's history of bumps looked like.
+  bump's `--title`, graded by `--impact`); every later bump of the *same* candidate updates that
+  entry in place - heading, date and the bumps list all move, but the entry's own prose is left
+  alone. `version notes` therefore still prints exactly one entry per release, whatever a
+  candidate's history of bumps looked like.
+- **The entry is layered, not one undifferentiated block.** A long-running candidate can collect
+  dozens of bumps, chronological and equally weighted, which is unreadable as a release
+  announcement - `5.0.0` did this at ~1440 lines for one entry. So the entry reads, top to bottom,
+  as four layers with different authors and different lifetimes:
+
+  1. **Heading, author, breaking/migration lines** - written by `version bump`, anchored right
+     above the bump list so the line an operator most needs to act on never sits beneath a list
+     that can run long.
+  2. **The bump list**, grouped `**High/Medium/Low impact**` (empty groups omitted) - rendered by
+     `version bump`'s `--impact` (default `medium`), corrected after the fact by `version regrade`.
+     Flat and ungrouped, exactly as before this layering existed, when every bump is `medium` - the
+     common case, and the shape every pre-existing region still is.
+  3. **The release summary** - a short paragraph, written once, by hand, when the candidate is
+     ready to ship. `version release` refuses to close an entry with two or more bumps and no
+     summary here; a one-bump entry is exempt, since there the bump's own changeset already reads
+     as the summary.
+  4. **The changesets**, one `### <bump title>` heading per bump, in chronological order - the
+     detail a reader follows into from the graded list above. A changeset is a few sentences,
+     not the full rationale; what needs more than that belongs in the issue tracker, not here.
+
+  The list is the index into the changesets, which is why the bump list's title text and a
+  changeset's `###` heading are the same string.
 - **`version bump` opens or continues a candidate; `version release` fixes one.** Only `release`
   strips the suffix and turns the entry into a real, closed release - see its own row in
   `tools/CONTRACT.md`. Nothing else does, and nothing auto-fixes a candidate on its own.
@@ -126,9 +148,12 @@ the three-line test below is usually enough.
 
    Then wait for an explicit go-ahead. Do not bump across the boundary on your own initiative.
 
-5. **Record the break in the escalation bump itself.** The bump that first crosses the boundary
-   requires `--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the
-   entry:
+5. **Grade the bump while you are making it, with `--impact high|medium|low`** (default
+   `medium`) - the judgment is easiest right after you did the work, not weeks later staring at a
+   chronological list. It is not final: `version regrade` corrects it before release if the
+   candidate's overall shape changes the read on an earlier bump. Then record the break in the
+   escalation bump itself. The bump that first crosses the boundary requires
+   `--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the entry:
 
    ```bash
    tools/wikitool version bump --major \
@@ -168,16 +193,27 @@ the three-line test below is usually enough.
    never reported by anything. The 5.0.0 candidate is the case: it declared `--no-migration` for
    a TOC-verification change, then absorbed a schema removal that migrates 152 pages.
 
-7. **Fix the candidate once it is ready to ship.** `version bump` only ever opens or escalates
-   one; nothing turns it into a release except `tools/wikitool version release`, which strips the
-   `-beta.N` suffix and closes the entry - see its row in `tools/CONTRACT.md`. That is also the
-   point to pass a summarising `--title` if the candidate collected several bump titles along the
-   way; without one, the heading simply keeps whichever bump last set it.
+7. **Review the graded list before fixing the candidate, and regrade what reads wrong.** Run
+   `tools/wikitool version regrade` with no arguments - it lists every bump at its current grade,
+   numbered in rendered order. A candidate that grew over several sessions often has a bump graded
+   in isolation that reads differently once the whole shape is visible; `version regrade 3 7
+   --impact high` corrects one or several positions against a single read of that list, put the
+   result in front of the user, and re-list to confirm. Only then run
+   `tools/wikitool version release`, which strips the `-beta.N` suffix and closes the entry - see
+   its row in `tools/CONTRACT.md`. That is also the point to pass a summarising `--title` if the
+   candidate collected several bump titles along the way; without one, the heading simply keeps
+   whichever bump last set it.
 
-8. **Write the entry's body.** `bump` leaves it empty on purpose. A boundary-crossing entry
-   earns a paragraph that says *why this is breaking* - it is the one thing a future reader
-   cannot reconstruct from the diff, and it is what the next session in this position will read
-   instead of guessing.
+8. **Write the entry's prose - the summary, and each bump's own changeset.** `bump` leaves both
+   empty on purpose. The **summary** is a short paragraph (a few sentences) written once, at
+   release time, right below the graded bump list: what this release is about, and why, for a
+   reader who will not read the changesets underneath. `version release` refuses to close an
+   entry that collected two or more bumps and has no summary - a one-bump entry is exempt, since
+   there the bump's changeset already reads as one. Each **changeset**, under its own
+   `### <bump title>` heading, is a few sentences on what changed and why - it is the one thing a
+   future reader cannot reconstruct from the diff, but it is not the place for the full rationale
+   of a decision; that belongs in the issue tracker or the commit history, and a changeset that
+   is growing past a paragraph or two is a sign it belongs there instead.
 
 ## Decision points