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

CHANGES.md

@@ -25,13 +25,112 @@ names it with a `-beta.N` suffix (`## 4.4.0-beta.2 - <date> - <title>`), and
 every bump of that same candidate updates this one entry in place rather than
 opening another: the heading's version/date/title move, and the bump's
 `--title` joins a machine-managed `<!-- wikitool:bumps -->` list right under
-the entry's `**Author:**` line - written and read by `wikitool version bump`,
+the entry's `**Author:**`/`**Breaking Change:**`/`**Migration:**` lines -
-never by hand. `wikitool version release` is what closes a candidate: it
+written and read by `wikitool version bump`, never by hand.
-strips the suffix and turns the entry into an ordinary, suffix-free one,
+
-leaving the bump-title list as the record of what happened. A distributed
+That list is graded, not a flat chronological dump: each bump carries an
-instance never sees a `-beta.` version at all (`release.yml` only ever
+impact (`--impact high|medium|low`, default `medium`), and the list renders
-releases a fixed one), so this suffix and the list beneath it are a
+grouped under `**High/Medium/Low impact**` headings - except when every bump
-dev-checkout concern - readable here, never shipped as something to parse.
+so far is `medium`, where it stays flat with no headings at all, exactly as
+it always did before grading existed. `wikitool version regrade` corrects a
+grade after the fact, against a single read of the whole list. Below the
+list comes a short summary paragraph, written once at release time, and below
+that one `### <bump title>` changeset per bump, in chronological order -
+`wikitool version release` refuses to close a candidate that collected two or
+more bumps and has no summary there (a one-bump candidate is exempt, since its
+single changeset already reads as one). This layering exists because a
+long-running candidate's bump list, left flat and ungraded, grows unreadable
+as a release announcement - the concrete case that forced it was `5.0.0`, one
+entry across roughly 1440 lines.
+
+`wikitool version release` is what closes a candidate: it strips the suffix
+and turns the entry into an ordinary, suffix-free one, leaving the bump list,
+summary and changesets as the record of what happened. A distributed instance
+never sees a `-beta.` version at all (`release.yml` only ever releases a fixed
+one), so the suffix and everything below the heading are a dev-checkout
+concern - readable here, never shipped as something to parse.
+
+---
+
+## 5.1.0 - 2026-09-12 - changelog: Kandidaten-Eintrag nach Impact gruppiert, version regrade zur Nachkorrektur, version release verlangt eine Zusammenfassung
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+**High impact**
+- changelog: Kandidaten-Eintrag nach Impact gruppiert, version regrade zur Nachkorrektur, version release verlangt eine Zusammenfassung
+<!-- /wikitool:bumps -->
+
+Seit `4.4.0` sammelt ein laufender Kandidat alle Bumps in einem Eintrag; bei `5.0.0` wurde das
+mit 20 Bumps und ~1440 Zeilen unlesbar, weil die Liste chronologisch und ungewichtet war und die
+Release-Seite genau diesen Eintrag 1:1 uebernimmt (`version notes`, `release.yml`). Der Eintrag
+ist jetzt geschichtet statt einer einzigen Wand Text: `version bump --impact high|medium|low`
+(Default `medium`) graduiert jeden Bump, die Liste rendert nach High/Medium/Low gruppiert - ausser
+wenn alles `medium` ist, dann bleibt sie flach wie bisher, damit jeder alte Eintrag und jeder
+einfache Patch unveraendert bleibt. `version regrade` korrigiert eine Note im Nachhinein, gegen
+einen einzelnen Lesevorgang der ganzen Liste, bevor der Kandidat geschlossen wird. Direkt unter
+der Liste steht jetzt eine kurze Zusammenfassung, darunter je Bump ein eigener
+`### <Bump-Titel>`-Changeset-Absatz; `version release` verweigert das Schliessen eines Kandidaten
+mit zwei oder mehr Bumps, solange diese Zusammenfassung fehlt (ein Kandidat mit genau einem Bump
+ist ausgenommen - sein Changeset ist bereits die Zusammenfassung, wie hier). Geschlossene
+Eintraege wie der zu `5.0.0` bleiben in der alten Form stehen: die Release-Seiten sind laut
+eigenem Footer unveraenderliche Snapshots, und `instructions/dev/version-parts.md` sowie
+`docs/version-model.md` zitieren den `2.0.0`-Eintrag mit Abschnittsnamen.
+
+`--breaking`/`**Migration:**` sitzen jetzt oberhalb der Bump-Liste statt darunter, damit die fuer
+einen Operator wichtigste Zeile nicht unter einer moeglicherweise langen Liste verschwindet.
+
+---
+
+## 5.0.1 - 2026-09-12 - publish: ungeborene main ist kein detached HEAD, erster Push zu leerem Remote (schliesst #96, #97)
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- publish: ungeborene main ist kein detached HEAD, erster Push zu leerem Remote (schliesst #96, #97)
+<!-- /wikitool:bumps -->
+
+Zwei Defekte, die zusammen dazu führten, dass eine frisch aufgesetzte Instanz
+sich über keinen dokumentierten Weg initial veröffentlichen ließ. Beide sitzen
+in `publish` und wurden erst beim Einrichten einer 5.0.0-Instanz aus dem
+Release-Tarball sichtbar - der Pfad, den `instructions/setup-instance.md`
+Schritt 14 als *den* ersten schreibenden Aufruf einer neuen Instanz nennt.
+
+**Ein ungeborener Branch ist kein detached HEAD.** `current_branch()` fragte
+`git rev-parse --abbrev-ref HEAD`. Nach `git init -b main`, vor dem ersten
+Commit, zeigt `HEAD` auf einen Ref, der sich nicht auflöst: `rev-parse` endet
+mit Exit 128 und war damit von einem echten detached HEAD nicht zu
+unterscheiden. Der erste `publish` einer neuen Instanz brach deshalb mit
+"Refusing to push `main` from a detached HEAD" ab, und Invariante 5 schneidet
+den naheliegenden Ausweg (`git commit` von Hand) ab. Die Funktion liest jetzt
+`git symbolic-ref --short -q HEAD` - was `HEAD` *benennt* statt worauf es
+zeigt. Damit beantwortet die Branch-Prüfung den ungeborenen Fall korrekt,
+statt für ihn ausgesetzt werden zu müssen: sie vergleicht `main` mit `main`
+und lässt durch. Ein echter detached HEAD wird unverändert abgelehnt, und ein
+`--branch`, das nicht dem ausgecheckten entspricht, ebenfalls.
+
+**Ein nie gepushter Branch ist nicht "nicht ahead".** `_local_ahead_of_remote()`
+entscheidet, ob ein sauberer Working-Tree trotzdem etwas zu pushen hat, und
+gab `False` zurück, sobald kein Tracking-Ref existierte. Genau das ist der Fall
+bei einem frisch angelegten, leeren Remote-Repository: der lokale Commit stand,
+`publish` meldete "Nothing to commit" und pushte nie - beliebig oft
+wiederholbar. Unterschieden wird jetzt über `git ls-remote --exit-code`, dessen
+Exit-Code die drei Lagen ohne Textvergleich trennt (0 = Ref vorhanden,
+2 = Remote erreichbar und ohne diesen Ref, 128 = unerreichbar oder gar nicht
+konfiguriert); auf die Meldung zu matchen schiede aus, weil git sie übersetzt.
+Nur der mittlere Fall gilt als "ahead", und auch dort nur, wenn lokal
+überhaupt ein Commit existiert. Ein unerreichbares Remote behält bewusst das
+bisherige Verhalten, damit Offline- und Nur-lokal-Instanzen keine
+Verhaltensänderung sehen. `remote_ref_exists()` bleibt unangetastet - sein
+zweiter Aufrufer `reconcile()` meint damit weiterhin richtig "nichts zum
+Abgleichen da".
+
+`tools/CONTRACT.md` zieht beides nach: die `publish`-Zeile beschrieb den
+Strandungsfall bisher als gelöst, was für einen nie gepushten Branch nicht
+stimmte, und der Fehlerkontrakt benennt die Branch-Prüfung jetzt als
+eigenständigen Exit-1-Grund. `instructions/setup-instance.md` und `INSTALL.md`
+blieben inhaltlich richtig - sie hatten den Umweg nie beschrieben, sondern den
+Weg, der jetzt tatsächlich funktioniert.
 
 ---
 

DEVELOPMENT.md

@@ -22,19 +22,24 @@ ein Release verbraucht wird - steht in
 [docs/version-model.md](docs/version-model.md). Hier nur der Ablauf, in der Reihenfolge, in der
 eine Sitzung ihn tatsächlich durchläuft:
 
-1. **Bump eröffnet oder eskaliert den Kandidaten.**
+1. **Bump eröffnet oder eskaliert den Kandidaten, gewichtet mit `--impact`.**
 
    ```bash
-   tools/wikitool version bump --minor --title "Was sich geändert hat"
+   tools/wikitool version bump --minor --title "Was sich geändert hat" --impact medium
    ```
 
    Schreibt `VERSION` als `X.Y.Z-beta.N` und öffnet (oder aktualisiert) den passenden
    `CHANGES.md`-Eintrag. Mehrere Bumps für dieselbe Änderung sind normal - jeder aktualisiert
-   denselben Eintrag, statt einen neuen zu eröffnen.
+   denselben Eintrag, statt einen neuen zu eröffnen. `--impact high|medium|low` (Default
+   `medium`) gruppiert den Eintrag; `tools/wikitool version regrade` korrigiert eine Note später,
+   wenn der Gesamteindruck des Kandidaten den Blick auf einen früheren Bump ändert.
 
-2. **Der Eintrag bekommt seine Prosa.** `bump` schreibt nur das Skelett (Heading, Datum, Autor,
+2. **Der Eintrag bekommt seine Prosa - zweigeteilt.** `bump` schreibt nur das Skelett (Heading,
-   die maschinenverwaltete Bump-Titel-Liste, ggf. Breaking-/Migration-Zeile). Der Fließtext
+   Datum, Autor, die maschinenverwaltete, gruppierte Bump-Titel-Liste, ggf.
-   darunter ist Autorenarbeit, wie bei `new` und der Seiten-Prosa.
+   Breaking-/Migration-Zeile). Darunter kommen zwei Autorenanteile: eine kurze Zusammenfassung
+   (ein paar Sätze, worum es in diesem Release geht) direkt unter der Liste, und darunter je Bump
+   ein eigener `### <Bump-Titel>`-Changeset-Absatz. Details dazu in
+   [instructions/dev/version-parts.md](instructions/dev/version-parts.md) § The candidate model.
 
 3. **Verify laufen lassen, bevor irgendetwas gepublished wird:**
 
@@ -52,8 +57,10 @@ eine Sitzung ihn tatsächlich durchläuft:
 
    Streicht den `-beta.N`-Suffix aus `VERSION` und schließt den Changelog-Eintrag. `--title` ist
    optional - ohne ihn bleibt der Titel des letzten Bumps stehen; mit ihm bekommt ein Kandidat,
-   der mehrere Bump-Titel gesammelt hat, eine zusammenfassende Überschrift. Committet und pusht
+   der mehrere Bump-Titel gesammelt hat, eine zusammenfassende Überschrift. Verweigert, wenn der
-   nichts (Invariante 5 in [AGENTS.md](AGENTS.md)).
+   Kandidat zwei oder mehr Bumps gesammelt hat und die Zusammenfassung aus Schritt 2 noch fehlt -
+   ein Kandidat mit genau einem Bump ist davon ausgenommen. Committet und pusht nichts
+   (Invariante 5 in [AGENTS.md](AGENTS.md)).
 
 5. **Publish bewegt `VERSION` auf `main`.**
 

VERSION

@@ -1 +1 @@
-5.0.0
+5.1.0

instructions/dev/stack-dev/SKILL.md

@@ -107,9 +107,14 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
    version and a changelog entry:
 
    ```bash
-   tools/wikitool version bump --patch --title "<what changed>"
+   tools/wikitool version bump --patch --title "<what changed>" --impact medium
    ```
 
+   `--impact high|medium|low` (default `medium`) grades this bump in the changelog entry's own
+   list - `tools/wikitool version regrade` corrects it later if the candidate's overall shape
+   changes the read on an earlier one; see
+   [instructions/dev/version-parts.md](../version-parts.md) § The candidate model.
+
    Never edit `VERSION` or the entry's heading by hand - `bump` writes both, and `docs verify`
    fails a tree where they disagree. Pick the part by whether the new version is a **drop-in
    replacement** for the old one - not by whether content has to be migrated:

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 -
+  bump's `--title`, graded by `--impact`); every later bump of the *same* candidate updates that
-  heading, date and the bumps list all move, but the entry's own prose (written below the
+  entry in place - heading, date and the bumps list all move, but the entry's own prose is left
-  skeleton, by hand) is left alone. `version notes` therefore still prints exactly one entry per
+  alone. `version notes` therefore still prints exactly one entry per release, whatever a
-  release, whatever a candidate's history of bumps looked like.
+  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
+5. **Grade the bump while you are making it, with `--impact high|medium|low`** (default
-   requires `--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the
+   `medium`) - the judgment is easiest right after you did the work, not weeks later staring at a
-   entry:
+   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
+7. **Review the graded list before fixing the candidate, and regrade what reads wrong.** Run
-   one; nothing turns it into a release except `tools/wikitool version release`, which strips the
+   `tools/wikitool version regrade` with no arguments - it lists every bump at its current grade,
-   `-beta.N` suffix and closes the entry - see its row in `tools/CONTRACT.md`. That is also the
+   numbered in rendered order. A candidate that grew over several sessions often has a bump graded
-   point to pass a summarising `--title` if the candidate collected several bump titles along the
+   in isolation that reads differently once the whole shape is visible; `version regrade 3 7
-   way; without one, the heading simply keeps whichever bump last set it.
+   --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
+8. **Write the entry's prose - the summary, and each bump's own changeset.** `bump` leaves both
-   earns a paragraph that says *why this is breaking* - it is the one thing a future reader
+   empty on purpose. The **summary** is a short paragraph (a few sentences) written once, at
-   cannot reconstruct from the diff, and it is what the next session in this position will read
+   release time, right below the graded bump list: what this release is about, and why, for a
-   instead of guessing.
+   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
 

tools/CONTRACT.md

@@ -150,7 +150,7 @@ tools/wikitool <command> --help
 | Command | Purpose |
 |---------|---------|
 | `sync [--remote origin] [--branch main] [--confirm-rebase TOKEN]` | Fetch `<remote>/<branch>` and bring the local branch up to date with it: fast-forward when the remote is simply ahead, rebase local commit(s) on top when both sides moved but touch disjoint files (a content conflict is then impossible by construction), and exit **42** for review when they touch the same file (the **rebase-review gate** - see `publish` below). Never commits, never pushes, never force-anything - no remote configured, or one that cannot be reached, is reported and skipped, not a failure. Meant to run once at the start of a writing session (`instructions/session-setup.md`) so the rest of it works against a current tree instead of discovering the drift at the final `publish` |
-| `publish --message "<op>: <desc>" [--no-push] [--confirm TOKEN] [--confirm-rebase TOKEN] [--threshold N] [--remote origin] [--branch main] [--path P ...]` | Reconcile with `<remote>/<branch>` exactly like `sync` (skipped for `--no-push`), then stage all changes, commit, and push. If the reconcile step found a still-unpushed local commit and there is nothing new to stage, that commit is pushed anyway - a previous `publish` whose push failed no longer strands it. If the push is rejected despite the pre-check (a genuine race - something landed on the remote in between), one more reconcile-and-retry is attempted before giving up; never more than one. **Mass-Update Gate:** when >= `--threshold` (default 10) *counted* files would be committed, exits **42 (`EXIT_NEEDS_CLEARANCE`)** instead of publishing - a third outcome distinct from success (0) and a validation error (1) - and prints a review report: a scale line (file count, total lines added/removed, status breakdown), only-what-applies attention notes (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn, generated files split out as needing no review. The token digests each counted path **and its contents** plus the publish target, so a clearance carries neither to a different file list nor to edited contents; a wrong, invented or superseded token exits 42 again with the current state. Two kinds of path are committed but never counted and never shown for approval: anything under `work/`, and the files `wikitool` generates itself (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md`) - each is recomputable from the tree, so approving it decides nothing, and a routine ingest rebuilds five or six of them. The refusal line accounts for both, by reason. The gate is evaluated *before* anything is staged, so a refused publish leaves the working tree untouched. **Publish-Remote Gate:** when this checkout carries a `.wikitool-remotes.json` and the resolved push URL of `--remote` is not listed in it, exits **42** before the reconcile step even fetches - the URL is read from `git remote get-url --push`, so a repointed remote does not pass on its name. Unlike the other two gates it has **no token and no flag**: the way past it is the user adding the URL to that file, and an agent editing it to get past a refusal is opening a gate on its own initiative. Absent file means unrestricted; a malformed one is an error, not permission. See [instructions/gates.md](../instructions/gates.md) `--yes`/`-y` are gone and now fail with an explicit error. `--path` (repeatable) scopes the whole operation - gate count, staging, and commit - to a subtree. **Stack-machinery note:** after a successful commit/push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md`, or a path ending in `CONTRACT.md` - roughly the scope a stack version bump covers, deliberately a shade broader than CI's version gate, which matches only a `CONTRACT.md` one segment deep - prints one reminder line that the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. Not a gate: no exit code change, nothing to clear, silent for an ordinary content publish |
+| `publish --message "<op>: <desc>" [--no-push] [--confirm TOKEN] [--confirm-rebase TOKEN] [--threshold N] [--remote origin] [--branch main] [--path P ...]` | Reconcile with `<remote>/<branch>` exactly like `sync` (skipped for `--no-push`), then stage all changes, commit, and push. Refuses before staging anything when the push target is not the checked-out branch, so a `git push <branch>` cannot quietly publish a ref other than the commit just made; the *unborn* branch of a fresh `git init -b main` counts as checked out, which is what lets the first publish of a new instance work (`instructions/setup-instance.md` step 14), while a genuine detached HEAD is still refused. If the reconcile step found a still-unpushed local commit and there is nothing new to stage, that commit is pushed anyway - a previous `publish` whose push failed no longer strands it, and neither does a branch the remote has never seen (a newly created, empty remote repository). A remote that cannot be reached at all is deliberately not read that way: it keeps reporting "Nothing to commit" on a clean tree rather than attempting a push, so an offline or local-only instance is unaffected. If the push is rejected despite the pre-check (a genuine race - something landed on the remote in between), one more reconcile-and-retry is attempted before giving up; never more than one. **Mass-Update Gate:** when >= `--threshold` (default 10) *counted* files would be committed, exits **42 (`EXIT_NEEDS_CLEARANCE`)** instead of publishing - a third outcome distinct from success (0) and a validation error (1) - and prints a review report: a scale line (file count, total lines added/removed, status breakdown), only-what-applies attention notes (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn, generated files split out as needing no review. The token digests each counted path **and its contents** plus the publish target, so a clearance carries neither to a different file list nor to edited contents; a wrong, invented or superseded token exits 42 again with the current state. Two kinds of path are committed but never counted and never shown for approval: anything under `work/`, and the files `wikitool` generates itself (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md`) - each is recomputable from the tree, so approving it decides nothing, and a routine ingest rebuilds five or six of them. The refusal line accounts for both, by reason. The gate is evaluated *before* anything is staged, so a refused publish leaves the working tree untouched. **Publish-Remote Gate:** when this checkout carries a `.wikitool-remotes.json` and the resolved push URL of `--remote` is not listed in it, exits **42** before the reconcile step even fetches - the URL is read from `git remote get-url --push`, so a repointed remote does not pass on its name. Unlike the other two gates it has **no token and no flag**: the way past it is the user adding the URL to that file, and an agent editing it to get past a refusal is opening a gate on its own initiative. Absent file means unrestricted; a malformed one is an error, not permission. See [instructions/gates.md](../instructions/gates.md) `--yes`/`-y` are gone and now fail with an explicit error. `--path` (repeatable) scopes the whole operation - gate count, staging, and commit - to a subtree. **Stack-machinery note:** after a successful commit/push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md`, or a path ending in `CONTRACT.md` - roughly the scope a stack version bump covers, deliberately a shade broader than CI's version gate, which matches only a `CONTRACT.md` one segment deep - prints one reminder line that the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. Not a gate: no exit code change, nothing to clear, silent for an ordinary content publish |
 
 ### Workshop runs and session budget
 
@@ -189,8 +189,9 @@ tools/wikitool <command> --help
 | `version show [--json]` | Print this instance's stack version and where it came from (development tree, or a distribution with its export date and origin). Bare `wikitool version` is an alias for this. Read-only, offline, and **exempt from the Iteration Budget Gate** |
 | `version check [--url U] [--timeout S] [--json]` | Ask the origin's release feed whether a newer stack exists, and whether the step crosses a compatibility boundary (`state: current\|update\|migration\|ahead`). **The only command in `wikitool` that makes a network call** - never reached implicitly from another command, needs no key, times out, and reports an unreachable feed as an error rather than as "up to date". The feed is `$WIKITOOL_UPDATE_URL`, else the release stamp's, else the built-in origin; `$WIKITOOL_UPDATE_TOKEN` is only needed if that feed is not readable anonymously. Read-only and exempt from the budget gate |
 | `version notes [--version X.Y.Z]` | Print one version's `CHANGES.md` entry, for use as release notes (default: this tree's `VERSION`). Read-only and exempt from the budget gate |
-| `version bump --major\|--minor\|--patch --title "<...>" [--breaking "<what breaks>"] [--no-migration "<reason>"] [--migration-required] [--dry-run]` | Raise or continue the **one running candidate** between two releases - `VERSION` gets a `-beta.N` suffix, never a second fresh number per bump. `--major/--minor/--patch` is **max-wins escalation** against the last release (patch < minor < major): a `--patch` on a MINOR candidate only advances `N`, and escalation never steps back down. Opens the matching `CHANGES.md` entry on the first bump of a candidate (heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list of every `--title` collected so far) and updates that same entry in place on every later bump of the same candidate - one entry per candidate, not one per bump. Refuses more or fewer than one part, an empty title, and a `VERSION`/newest-changelog-entry mismatch. Compatibility follows the **leftmost non-zero component** of the candidate's base, which for this stack (at `1.0.0` and up) means MAJOR: PATCH is a fix, MINOR a compatible capability, MAJOR a version that is **not a drop-in replacement** - any hand-work on update, or a downgrade that no longer works. Whether content must be migrated is a second, independent question. The bump that first escalates a candidate past the boundary requires `--breaking "<what stops working>"` and, on top of it, a migration document targeting the candidate's base or `--no-migration "<reason>"`; both lines are written once and persist over later bumps of the same candidate without being repeated, and both are refused on a bump that crosses nothing at all. A later bump of the same candidate that finds out `--no-migration` was wrong after all retracts that line with `--migration-required` instead of restating `--no-migration` - refused without a migration document already targeting the new base, and without an existing `--no-migration` line to retract. Which part a change earns stays a judgment call: the command enforces that a crossing documents itself, never that the part was chosen correctly |
+| `version bump --major\|--minor\|--patch --title "<...>" [--impact high\|medium\|low] [--breaking "<what breaks>"] [--no-migration "<reason>"] [--migration-required] [--dry-run]` | Raise or continue the **one running candidate** between two releases - `VERSION` gets a `-beta.N` suffix, never a second fresh number per bump. `--major/--minor/--patch` is **max-wins escalation** against the last release (patch < minor < major): a `--patch` on a MINOR candidate only advances `N`, and escalation never steps back down. Opens the matching `CHANGES.md` entry on the first bump of a candidate (heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list of every `--title` collected so far, graded by `--impact`, default `medium`) and updates that same entry in place on every later bump of the same candidate - one entry per candidate, not one per bump. The list renders grouped under `**High/Medium/Low impact**` headings (empty groups omitted), except when every bump so far is `medium`, where it stays the flat, ungrouped list the region always had - `version regrade` corrects a grade after the fact. Refuses more or fewer than one part, an empty title, an unknown `--impact`, and a `VERSION`/newest-changelog-entry mismatch. Compatibility follows the **leftmost non-zero component** of the candidate's base, which for this stack (at `1.0.0` and up) means MAJOR: PATCH is a fix, MINOR a compatible capability, MAJOR a version that is **not a drop-in replacement** - any hand-work on update, or a downgrade that no longer works. Whether content must be migrated is a second, independent question. The bump that first escalates a candidate past the boundary requires `--breaking "<what stops working>"` and, on top of it, a migration document targeting the candidate's base or `--no-migration "<reason>"`; both lines are written once, anchored just above the bump list, and persist over later bumps of the same candidate without being repeated, and both are refused on a bump that crosses nothing at all. A later bump of the same candidate that finds out `--no-migration` was wrong after all retracts that line with `--migration-required` instead of restating `--no-migration` - refused without a migration document already targeting the new base, and without an existing `--no-migration` line to retract. Which part a change earns stays a judgment call: the command enforces that a crossing documents itself, never that the part was chosen correctly |
-| `version release [--title "<...>"] [--dry-run]` | Fix the running candidate: strip `VERSION`'s `-beta.N` suffix and close its `CHANGES.md` entry, ending the pre-release phase `version bump` started. Without `--title` the heading keeps whichever bump last set it; with it, the heading's title is replaced - the normal case for a candidate that collected several bump titles, since the entry wants a summarising heading rather than the most recent one. Leaves the entry's machine-managed bump-title list untouched, as the record of what happened. Commits nothing and pushes nothing (invariant 5) - the following `publish` moves `VERSION` onto `main`, which `release.yml` reacts to. Refuses when `VERSION` is already a release (no running candidate to fix), or when the changelog's newest entry does not match `VERSION` |
+| `version regrade [INDICES...] [--impact high\|medium\|low]` | List the running candidate's bump titles with their impact grade and 1-based rendered position (no arguments - the correction path for a `--impact` judgement made at bump time), or change one or more of them in a single call: `version regrade 3 7 --impact high` grades both against a single read of today's list, not position 3 first and then position 7 against whatever that produced. Touches only the topmost entry's bump list - never `VERSION`, never any other part of `CHANGES.md`. The bare listing is read-only and exempt from the Iteration Budget Gate, like `version notes`; a call with indices writes `CHANGES.md` and is counted like `version bump`. Refuses an index outside the rendered list's range, an unknown `--impact`, indices given without `--impact`, a missing `VERSION`/`CHANGES.md`, a `VERSION`/newest-changelog-entry mismatch, or a topmost entry with no bump list at all |
+| `version release [--title "<...>"] [--dry-run]` | Fix the running candidate: strip `VERSION`'s `-beta.N` suffix and close its `CHANGES.md` entry, ending the pre-release phase `version bump` started. Without `--title` the heading keeps whichever bump last set it; with it, the heading's title is replaced - the normal case for a candidate that collected several bump titles, since the entry wants a summarising heading rather than the most recent one. Leaves the entry's machine-managed bump-title list untouched, as the record of what happened. Refuses when the candidate collected two or more bumps and the entry still carries no summary paragraph (at least 200 non-whitespace characters) between the bump list and the first `### <bump title>` changeset heading; a candidate with exactly one bump is exempt, since there its own changeset already is the summary. `--dry-run` runs this check too and reports the same refusal. Commits nothing and pushes nothing (invariant 5) - the following `publish` moves `VERSION` onto `main`, which `release.yml` reacts to. Refuses when `VERSION` is already a release (no running candidate to fix), or when the changelog's newest entry does not match `VERSION` |
 
 ### Content migrations
 
@@ -360,7 +361,7 @@ is atomic, and whether a retry is safe.
 | Command | Exit 1 means | Atomic? | Retry policy |
 |---------|--------------|---------|--------------|
 | `sync` | The automatic rebase hit a real conflict (git failed) | No - fetch, then at most one merge/rebase attempt, aborted cleanly on failure | For a conflict: **do not retry, do not force** - resolve manually and re-run. **Exit 42, not 1**, when the rebase-review gate needs clearance: show the user the command's full output verbatim (upstream commits, the overlapping files, their diff) and stop; re-running with `--confirm-rebase <token>` clears it, and a wrong, invented, or superseded token exits 42 again with the current state. No remote configured, or one that cannot be reached, is not a failure - reported and skipped |
-| `publish` | git failed, **or** `--yes`/`-y` was passed. **Exit 42, not 1**, when the Mass-Update Gate, the rebase-review gate (raised by the same reconcile `sync` performs), or the Publish-Remote Gate refuses | No - sequential git operations, but both gates run before staging | For git failures: **do not retry, do not force** - report and ask the user (the reconcile step already retried the push once on its own, if a rebase resolved the rejection). For exit 42: show the user the command's full output verbatim and stop; it names the evidence and the `--confirm <token>` or `--confirm-rebase <token>` line to re-run, and re-running without it exits 42 again. The Publish-Remote Gate is the exception with no such line: it names the push URL that would have been written to and the ones this checkout allows, and only the user resolves it |
+| `publish` | git failed, the push target is not the checked-out branch (including a real detached HEAD - but *not* the unborn branch of a fresh `git init`, which is a normal first publish), **or** `--yes`/`-y` was passed. **Exit 42, not 1**, when the Mass-Update Gate, the rebase-review gate (raised by the same reconcile `sync` performs), or the Publish-Remote Gate refuses | No - sequential git operations, but both gates run before staging | For git failures: **do not retry, do not force** - report and ask the user (the reconcile step already retried the push once on its own, if a rebase resolved the rejection). For exit 42: show the user the command's full output verbatim and stop; it names the evidence and the `--confirm <token>` or `--confirm-rebase <token>` line to re-run, and re-running without it exits 42 again. The Publish-Remote Gate is the exception with no such line: it names the push URL that would have been written to and the ones this checkout allows, and only the user resolves it |
 
 ### Workshop runs and session budget
 
@@ -399,8 +400,9 @@ is atomic, and whether a retry is safe.
 | `version show` | `VERSION` is missing or unparseable | Read-only | Fix `VERSION` and retry |
 | `version check` | The feed could not be reached, answered non-JSON, or carried no `tag_name`. **Never** answers "up to date" for a question it could not ask | Read-only, no local writes | A network failure is transient - retry once, then report it. HTTP 401/403 names `$WIKITOOL_UPDATE_TOKEN`; 404 means no release exists yet or the URL points at the wrong repo |
 | `version notes` | An unparseable `--version`, an unreadable `VERSION` when `--version` is omitted, a missing `CHANGES.md`, or no entry naming the requested version | Read-only | Fix the named argument or file, then retry. Safe to retry |
-| `version bump` | More or fewer than one of `--major/--minor/--patch`, an empty `--title`, a missing `VERSION`/`CHANGES.md`, `VERSION` and the changelog's newest entry naming different versions, an escalation to a boundary crossing without `--breaking` or with neither a migration document nor `--no-migration`, `--breaking`/`--no-migration` on a bump that crosses nothing, or `--migration-required` combined with `--no-migration`, on a bump with no running candidate, with no `--no-migration` line to retract, or without a migration document already targeting the new base | No - `VERSION` then `CHANGES.md` | **Not idempotent**: a second run escalates or continues the candidate again. If the outcome is uncertain, read `VERSION` and the top of `CHANGES.md` before retrying |
+| `version bump` | More or fewer than one of `--major/--minor/--patch`, an empty `--title`, an unknown `--impact`, a missing `VERSION`/`CHANGES.md`, `VERSION` and the changelog's newest entry naming different versions, an escalation to a boundary crossing without `--breaking` or with neither a migration document nor `--no-migration`, `--breaking`/`--no-migration` on a bump that crosses nothing, or `--migration-required` combined with `--no-migration`, on a bump with no running candidate, with no `--no-migration` line to retract, or without a migration document already targeting the new base | No - `VERSION` then `CHANGES.md` | **Not idempotent**: a second run escalates or continues the candidate again. If the outcome is uncertain, read `VERSION` and the top of `CHANGES.md` before retrying |
-| `version release` | A missing `VERSION`/`CHANGES.md`, `VERSION` already a release (no running candidate), or `VERSION` and the changelog's newest entry naming different versions | No - `VERSION` then `CHANGES.md` | **Not idempotent**: a second run fails outright once the suffix is gone. If the outcome is uncertain, read `VERSION` before retrying - a release-shaped `VERSION` means it already ran |
+| `version regrade` | A missing `VERSION`/`CHANGES.md`, `VERSION` and the changelog's newest entry naming different versions, a topmost entry with no bump list, an index outside the rendered list's range, indices given without `--impact`, or an unknown `--impact` | No - `CHANGES.md` only, and only when indices are given | The bare listing never writes anything. A write is **not idempotent** against a changed list: re-running the same indices after a first success regrades whatever is at those positions *now*, which may no longer be the same bumps - list again before retrying |
+| `version release` | A missing `VERSION`/`CHANGES.md`, `VERSION` already a release (no running candidate), `VERSION` and the changelog's newest entry naming different versions, or (from two bumps on) an entry with no summary paragraph above the changesets | No - `VERSION` then `CHANGES.md` | **Not idempotent**: a second run fails outright once the suffix is gone. If the outcome is uncertain, read `VERSION` before retrying - a release-shaped `VERSION` means it already ran |
 
 ### Content migrations
 

tools/README.md

@@ -91,11 +91,16 @@ bound at import time - `KB_DIR` and friends follow whatever `ROOT` currently is.
 5. Raise the version: `wikitool version bump --minor --title "..."` for a new
    command (`--patch` for a fix, `--major` when the new version is **not a
    drop-in replacement** - a renamed flag or artefact, a stricter check that
-   newly fails on content an instance already had, anything needing hand-work
+   newly fails on **shipped content an instance already had** (a `kb/` page,
-   after the copy). Content migration is one way to land there, not the
+   an `instructions/*.md` file), anything needing hand-work after the copy).
-   definition of it: a `--major` may well ship `--no-migration`, and one that
+   A new command that is merely pickier about its *own* fresh input - a flag
-   does migrate also needs a document under `instructions/migrations/`. The
+   it did not previously accept, a write it now refuses without more from the
-   full test is `instructions/dev/version-parts.md` - read it before choosing
+   caller - is the ordinary MINOR case: nothing an instance already has stops
+   validating, there is simply more to say when the command is next invoked.
+   Content migration is one way to land in the MAJOR row, not the definition
+   of it: a `--major` may well ship `--no-migration`, and one that does
+   migrate also needs a document under `instructions/migrations/`. The full
+   test is `instructions/dev/version-parts.md` - read it before choosing
    `--major`.
    A new command reaches every future instance, and CI's version gate refuses a
    stack change that moved no version.

tools/chemenu/commands/git_publish.py

@@ -348,12 +348,22 @@ def _changed_files(paths: list[str]) -> list[str]:
 
 
 def current_branch() -> Optional[str]:
-    """The checked-out branch, or None in a detached HEAD / non-checkout."""
+    """The checked-out branch, or None in a detached HEAD / non-checkout.
-    result = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+
+    `git symbolic-ref` and not `git rev-parse --abbrev-ref`, because the two disagree on
+    exactly the state a brand-new instance is in. On an *unborn* branch - `git init -b main`,
+    no commit yet, which is where `instructions/setup-instance.md` calls `publish` for the
+    first time - `HEAD` points at a ref that does not resolve, so `rev-parse` exits 128 and
+    the caller cannot tell it apart from a real detached HEAD. `symbolic-ref` reads what HEAD
+    *names* rather than what it resolves to, so it answers `main` there, empty (exit 1) on a
+    detached HEAD, and the branch name in the ordinary case - the distinction the branch check
+    below actually needs.
+    """
+    result = _run(["git", "symbolic-ref", "--short", "-q", "HEAD"])
     if result.returncode != 0:
         return None
     name = result.stdout.strip()
-    return None if not name or name == "HEAD" else name
+    return name or None
 
 
 def branch_mismatch_message(checked_out: Optional[str], branch: str) -> str:
@@ -877,13 +887,39 @@ def reconcile(remote: str, branch: str, confirm_rebase: Optional[str] = None) ->
     )
 
 
+def remote_lacks_branch(remote: str, branch: str) -> bool:
+    """Whether `remote` is reachable *and* has no `branch` on it - the brand-new instance whose
+    remote repository was created empty, as distinct from a remote nobody can reach at all.
+
+    `git ls-remote --exit-code` separates the two by exit code alone: 0 when the ref is there,
+    2 when the remote answered and does not have it, 128 when the remote could not be reached
+    (a bad URL, no network, refused auth) or is not configured. Reading the code rather than the
+    message is not a style preference - git translates `fatal: couldn't find remote ref main`,
+    so matching on the text would work only in an English locale.
+    """
+    return _run(["git", "ls-remote", "--exit-code", remote, branch]).returncode == 2
+
+
+def _has_commits(branch: str) -> bool:
+    """Whether `branch` points at anything yet - false on the unborn branch of a fresh
+    `git init`, where there is nothing that could be ahead of anything."""
+    result = _run(["git", "rev-list", "--count", "-n", "1", branch])
+    return result.returncode == 0 and result.stdout.strip() not in ("", "0")
+
+
 def _local_ahead_of_remote(remote: str, branch: str) -> bool:
     """Whether `branch` currently has a commit `<remote>/<branch>` lacks - true right after a
     stranded commit from a previous failed push, and also right after `reconcile` rebases local
     work on top of a moved remote. Used to decide whether an otherwise-empty working tree still
     has something to push."""
     if not remote_ref_exists(remote, branch):
-        return False
+        # No tracking ref, which `remote_ref_exists` cannot tell apart from an unreachable
+        # remote - and the very first publish of an instance lands here. A remote that answers
+        # and simply has no such branch yet means every local commit is unpushed, which is
+        # precisely the stranded state above; an unreachable one keeps the old answer, so an
+        # offline or local-only instance sees no new behaviour and the eventual `git push`
+        # (when there is something to stage) still reports the real error.
+        return remote_lacks_branch(remote, branch) and _has_commits(branch)
     result = _run(["git", "rev-list", "--count", f"{remote}/{branch}..{branch}"])
     return result.returncode == 0 and result.stdout.strip() not in ("", "0")
 

tools/chemenu/commands/run_budget.py

@@ -125,7 +125,15 @@ def is_exempt(command: str, args: list[str]) -> bool:
     if command in SKIP_COMMANDS:
         return True
     subcommand = args[0] if args and not args[0].startswith("-") else ""
-    return (command, subcommand) in SKIP_COMMAND_PATHS
+    if (command, subcommand) in SKIP_COMMAND_PATHS:
+        return True
+    # `version regrade` only reads when called with no further arguments at
+    # all - the bare listing. Any index (with `--impact`) writes CHANGES.md
+    # and stays counted like `version bump`, so this cannot join
+    # SKIP_COMMAND_PATHS, which only ever looks at the subcommand slot.
+    if command == "version" and subcommand == "regrade":
+        return len(args) == 1
+    return False
 
 
 def _session_id() -> str:

tools/chemenu/commands/version_cmd.py

@@ -11,7 +11,14 @@ number means, and `instructions/dev/version-parts.md` for the candidate model):
   holds the two together.
 - `version release` fixes that candidate: strips its `-beta.N` suffix and
   closes its changelog entry. It is the only thing that turns a candidate into
-  a number a release actually consumes.
+  a number a release actually consumes. Refuses if the candidate collected
+  more than one bump and its entry still carries no summary above the
+  changesets - see `version_mod.summary_prose`.
+- `version regrade` lists or changes the impact grade (high/medium/low) of
+  the running candidate's bump titles, addressed by their position in the
+  rendered list - the correction path for the judgment `version bump
+  --impact` made at the time, per Gitea #95's fix for an unreadably long,
+  ungraded bump list.
 - `version check` is the one command in `wikitool` that makes a network call.
   It is deliberately its own command: nothing else reaches for it implicitly,
   it needs no key, it times out, and a feed that cannot be reached is reported
@@ -20,6 +27,7 @@ number means, and `instructions/dev/version-parts.md` for the candidate model):
 from __future__ import annotations
 
 import json as _json
+import re
 from typing import Optional
 
 import typer
@@ -210,6 +218,13 @@ def bump_command(
         "Requires a migration document already targeting the new base, and refuses when the entry "
         "carries no --no-migration line to retract.",
     ),
+    impact: Optional[str] = typer.Option(
+        None,
+        "--impact",
+        help="high|medium|low - how much this bump matters to a reader of the release notes "
+        "(default: medium). Grouped into the entry's bump list; `version regrade` corrects it "
+        "later if the running candidate's own judgment changes.",
+    ),
     dry_run: bool = typer.Option(False, "--dry-run", help="Report the change without writing"),
 ):
     """Raise or continue the running candidate, and open or update its
@@ -242,6 +257,10 @@ def bump_command(
     if not title.strip():
         fail("--title must not be empty - it becomes the changelog entry's heading")
         return
+    if impact is not None and impact not in version_mod.IMPACT_LEVELS:
+        fail(f"--impact must be one of {', '.join(version_mod.IMPACT_LEVELS)}, not {impact!r}")
+        return
+    chosen_impact = impact or version_mod.DEFAULT_IMPACT
 
     try:
         current = version_mod.read_version()
@@ -351,13 +370,15 @@ def bump_command(
             no_migration_reason=no_migration.strip() if no_migration else None,
             breaking_reason=breaking.strip() if breaking else None,
             migration_required=migration_required,
+            impact=chosen_impact,
         ),
         encoding="utf-8",
     )
+    impact_note = "" if impact is not None else f" (impact not given - assumed {chosen_impact})"
     success(
         f"{current} -> {new_version}{boundary}. Wrote {version_mod.VERSION_FILENAME} and "
-        f"the {version_mod.CHANGES_FILENAME} entry - write its prose before publishing, and "
+        f"the {version_mod.CHANGES_FILENAME} entry{impact_note} - write its prose before "
-        f"`version release` once the candidate is ready to ship."
+        f"publishing, and `version release` once the candidate is ready to ship."
     )
 
 
@@ -382,7 +403,12 @@ def release_command(
     Commits nothing and pushes nothing (AGENTS.md invariant 5) - the following
     `publish` moves `VERSION` onto `main` and is what `release.yml` reacts to.
     Refuses when `VERSION` is already a release: there is no running candidate
-    to fix."""
+    to fix. Also refuses - Gitea #95 - when the candidate collected two or
+    more bumps and its entry still has no summary paragraph above the
+    individual changesets: a release note that is only a chronological bump
+    list is exactly the thing this refusal exists to stop shipping. A
+    candidate with exactly one bump is exempt - there, the bump's own
+    changeset already is the summary."""
     try:
         current = version_mod.read_version()
     except VersionError as exc:
@@ -412,6 +438,18 @@ def release_command(
         )
         return
 
+    section = version_mod.changes_section(text, current) or ""
+    bump_count = len(version_mod.bump_entries(section))
+    summary_chars = len(re.sub(r"\s+", "", version_mod.summary_prose(section)))
+    if bump_count >= 2 and summary_chars < version_mod.SUMMARY_MIN_CHARS:
+        fail(
+            f"This candidate collected {bump_count} bumps, but its {version_mod.CHANGES_FILENAME} "
+            "entry carries no summary above the individual changesets - write a short paragraph "
+            "(a few sentences on what this release is about) right below the bump list before "
+            "releasing. `version regrade` (no arguments) shows the bump list first, if that helps."
+        )
+        return
+
     new_version = current.base
 
     if dry_run:
@@ -428,3 +466,77 @@ def release_command(
         f"{version_mod.CHANGES_FILENAME} entry - `publish` next, which moves VERSION onto main and "
         "is what release.yml reacts to."
     )
+
+
+@app.command("regrade")
+def regrade_command(
+    indices: Optional[list[int]] = typer.Argument(
+        None,
+        help="1-based positions in the rendered bump list to regrade (see the bare listing). "
+        "Omit to just list.",
+    ),
+    impact: Optional[str] = typer.Option(
+        None, "--impact", help="high|medium|low - required together with indices"
+    ),
+):
+    """List the running candidate's bump titles with their impact grade, or
+    change one or more of them in a single call.
+
+    Positions are `version_mod.bump_entries`'s own rendered order - grouped
+    High before Medium before Low, chronological within a grade - as it
+    stands *before* this call: `wikitool version regrade 3 7 --impact high`
+    regrades both against today's list in one read, not #3 first and then #7
+    against whatever regrading #3 produced. Run the bare command again
+    afterwards to see the result and its new numbering.
+
+    The bare listing is read-only and, like `version notes`, exempt from the
+    Iteration Budget Gate; passing indices writes `CHANGES.md` and is counted
+    like `version bump`, because that is what it does."""
+    try:
+        current = version_mod.read_version()
+    except VersionError as exc:
+        fail(str(exc))
+        return
+
+    changes = version_mod.changes_file()
+    if not changes.is_file():
+        fail(f"{version_mod.CHANGES_FILENAME} is missing - there is nothing to regrade")
+        return
+    text = changes.read_text(encoding="utf-8")
+
+    top_entry = version_mod.top_changes_version(text)
+    if top_entry != current:
+        fail(
+            f"{version_mod.CHANGES_FILENAME}'s newest entry is {top_entry}, but "
+            f"{version_mod.VERSION_FILENAME} is {current} - they must agree before a regrade. "
+            "Fix whichever is wrong."
+        )
+        return
+
+    section = version_mod.changes_section(text, current) or ""
+    entries = version_mod.bump_entries(section)
+    if not entries:
+        fail(f"{current}'s {version_mod.CHANGES_FILENAME} entry has no bump list to regrade.")
+        return
+
+    if not indices:
+        for position, (level, bump_title) in enumerate(entries, start=1):
+            typer.echo(f"{position}. [{level}] {bump_title}")
+        return
+
+    if impact is None:
+        fail("--impact is required when regrading - pass one of high/medium/low.")
+        return
+    if impact not in version_mod.IMPACT_LEVELS:
+        fail(f"--impact must be one of {', '.join(version_mod.IMPACT_LEVELS)}, not {impact!r}")
+        return
+
+    updates = {index: impact for index in indices}
+    try:
+        new_text = version_mod.regrade(text, current, updates)
+    except VersionError as exc:
+        fail(str(exc))
+        return
+
+    changes.write_text(new_text, encoding="utf-8")
+    success(f"Regraded {len(indices)} bump title(s) to {impact} impact.")

tools/chemenu/tests/test_git_publish.py

@@ -19,6 +19,7 @@ from chemenu.commands.git_publish import (
     clearance_message,
     collect_changes,
     counted_files,
+    current_branch,
     describe_status,
     format_changes,
     group_of,
@@ -27,6 +28,7 @@ from chemenu.commands.git_publish import (
     parse_porcelain_z,
     publish_command,
     reconcile,
+    remote_lacks_branch,
     rerun_command,
     scale_line,
     sync_command,
@@ -342,6 +344,41 @@ def repo(tmp_path, monkeypatch):
     return root
 
 
+@pytest.fixture
+def fresh_instance(tmp_path, monkeypatch):
+    """A brand-new instance as `instructions/setup-instance.md` builds one: `git init -b main`,
+    an identity, a remote pointing at an *empty* repository, and no commit anywhere - neither
+    locally nor on the remote.
+
+    Deliberately not the `repo` fixture with a step removed. That one makes an initial commit
+    and pushes it, which is exactly the state the first publish of an instance has not reached
+    yet: the local branch is unborn and the remote has no `main`. Both defects this covers live
+    in that gap.
+    """
+    root = tmp_path / "instance"
+    remote = tmp_path / "empty-remote.git"
+    root.mkdir()
+    subprocess.run(["git", "init", "-b", "main", "--bare", str(remote)], check=True, capture_output=True)
+    _git(root, "init", "-b", "main")
+    _git(root, "config", "user.name", "Test")
+    _git(root, "config", "user.email", "test@example.com")
+    _git(root, "remote", "add", "origin", str(remote))
+    (root / "kb").mkdir()
+    (root / "README.md").write_text("fresh instance\n", encoding="utf-8")
+
+    monkeypatch.setattr(config, "ROOT", root)
+    monkeypatch.setenv("WIKITOOL_SESSION_ID", "test-session")
+    return root
+
+
+def _remote_log(remote_path):
+    """The remote's one-line log, or "" for a remote with no commits at all - `git log` exits
+    non-zero on an empty repository, so `_git`'s assertion cannot be used here."""
+    return subprocess.run(
+        ["git", "log", "--oneline"], cwd=remote_path, capture_output=True, text=True,
+    ).stdout
+
+
 def _write_files(root, n, prefix="kb/page"):
     for i in range(n):
         (root / f"{prefix}{i}.md").write_text(f"page {i}\n", encoding="utf-8")
@@ -724,6 +761,94 @@ def test_publish_pushes_a_stranded_local_commit_with_no_new_changes(repo):
     assert "stranded commit" in remote_log
 
 
+def test_current_branch_names_an_unborn_branch_rather_than_calling_it_detached(fresh_instance):
+    """`git init -b main` with no commit yet: HEAD names `main` but does not resolve. Reporting
+    None here is what made the documented first publish of an instance fail as a detached HEAD."""
+    assert current_branch() == "main"
+
+
+def test_current_branch_still_reports_a_real_detached_head_as_none(fresh_instance):
+    """The other half of the same distinction - the state the refusal is actually for."""
+    _git(fresh_instance, "add", "-A")
+    _git(fresh_instance, "commit", "-m", "first")
+    head = _git(fresh_instance, "rev-parse", "HEAD").stdout.strip()
+    _git(fresh_instance, "checkout", "--detach", head)
+
+    assert current_branch() is None
+
+
+def test_publish_makes_the_first_commit_of_a_new_instance(fresh_instance):
+    """The exact `setup-instance.md` step 14 scenario: unborn `main`, empty remote, nothing but
+    untracked files. It must commit and push, not refuse as a detached HEAD."""
+    _publish(message="chore: initial instance setup", threshold=100)
+
+    assert "initial instance setup" in _remote_log(fresh_instance.parent / "empty-remote.git")
+
+
+def test_publish_on_an_unborn_branch_still_refuses_a_different_target_branch(fresh_instance):
+    """Naming the unborn branch does not weaken the branch check - it makes it answerable. A
+    push aimed elsewhere is refused with the same `--branch` hint as on any other checkout."""
+    with pytest.raises(typer.Exit) as excinfo:
+        _publish(message="change", branch="feature", threshold=100)
+
+    assert excinfo.value.exit_code == 1
+    assert _remote_log(fresh_instance.parent / "empty-remote.git") == ""
+
+
+def test_the_gate_still_holds_on_a_fresh_instance_and_stages_nothing(fresh_instance):
+    """A real distribution is far over the threshold at step 14, so the first publish is meant
+    to end at the gate - and leave the tree untouched, which has to hold with no HEAD to
+    compare against either."""
+    _write_files(fresh_instance, 10)
+
+    with pytest.raises(typer.Exit) as excinfo:
+        _publish(message="chore: initial instance setup")
+
+    assert excinfo.value.exit_code == EXIT_NEEDS_CLEARANCE
+    # Nothing staged, nothing committed: all 11 files (10 pages plus the fixture's README)
+    # are still untracked, and the branch is still unborn.
+    status = _git(fresh_instance, "status", "--porcelain", "-uall").stdout.strip().splitlines()
+    assert len(status) == 11 and all(line.startswith("??") for line in status)
+    assert current_branch() == "main" and not git_publish._has_commits("main")
+    assert _remote_log(fresh_instance.parent / "empty-remote.git") == ""
+
+
+def test_publish_pushes_a_committed_stand_to_a_remote_that_has_no_branch_yet(fresh_instance):
+    """The `--no-push`-then-`publish` chain: the commit exists, the working tree is clean, and
+    the remote has never seen this branch. "Nothing to commit" here strands the commit forever,
+    because invariant 5 rules out a hand-made `git push`."""
+    _publish(message="chore: initial instance setup", push=False, threshold=100)
+    assert _remote_log(fresh_instance.parent / "empty-remote.git") == ""
+
+    _publish(message="chore: initial instance setup", threshold=100)
+
+    assert "initial instance setup" in _remote_log(fresh_instance.parent / "empty-remote.git")
+
+
+def test_an_unborn_branch_is_not_ahead_of_an_empty_remote(fresh_instance):
+    """Nothing committed anywhere: there is no commit that could be ahead, and claiming
+    otherwise would send `publish` into a push of nothing."""
+    assert git_publish._local_ahead_of_remote("origin", "main") is False
+
+
+def test_an_unreachable_remote_is_not_mistaken_for_one_that_lacks_the_branch(fresh_instance):
+    """"Cannot reach the remote" and "the remote has no such branch" both leave no tracking ref.
+    Only the second means every local commit is unpushed; treating the first that way would turn
+    every offline publish into a failed push."""
+    _git(fresh_instance, "add", "-A")
+    _git(fresh_instance, "commit", "-m", "local only")
+    _git(fresh_instance, "remote", "set-url", "origin", str(fresh_instance.parent / "nope.git"))
+
+    assert remote_lacks_branch("origin", "main") is False
+    assert git_publish._local_ahead_of_remote("origin", "main") is False
+
+
+def test_a_reachable_remote_without_the_branch_is_told_apart_from_one_that_has_it(repo):
+    """The positive half, on the fixture whose remote genuinely carries `main`."""
+    assert remote_lacks_branch("origin", "main") is False
+    assert remote_lacks_branch("origin", "never-pushed") is True
+
+
 def test_publish_auto_rebases_a_disjoint_divergence(repo):
     """The writer's change and this session's change touch different files: (a) alone is
     enough, so this must go straight through - no exit 42."""

tools/chemenu/tests/test_run_budget.py

@@ -189,6 +189,19 @@ def test_search_exemption_survives_a_query_that_looks_like_a_subcommand():
     assert not run_budget.is_exempt("publish", ["--message", "x"])
 
 
+def test_version_regrade_bare_listing_is_exempt():
+    """Gitea #95: `version regrade` only reads when called with no further
+    arguments at all - the listing form. It cannot join SKIP_COMMAND_PATHS
+    (that dict only ever looks at the subcommand slot), so it is its own
+    branch in `is_exempt`."""
+    assert run_budget.is_exempt("version", ["regrade"])
+
+
+def test_version_regrade_with_indices_is_counted():
+    assert not run_budget.is_exempt("version", ["regrade", "1", "--impact", "high"])
+    assert not run_budget.is_exempt("version", ["regrade", "3"])
+
+
 def test_reset_command_requires_yes():
     run_budget.record_and_check("new", ["entity", "--name", "X"], override=False)
     with pytest.raises(typer.Exit):

tools/chemenu/tests/test_version_cmd.py

@@ -34,6 +34,17 @@ def tree(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     return tmp_path
 
 
+def _write_summary(tree: Path, words: str = "Summary paragraph. ") -> None:
+    """Append enough non-whitespace prose above the changesets for `version
+    release`'s summary requirement to pass - the way an author's own edit
+    would, between the bumps region and any `### <bump title>` heading."""
+    path = tree / "CHANGES.md"
+    text = path.read_text(encoding="utf-8")
+    marker = version_mod._BUMPS_CLOSE + "\n"
+    assert marker in text
+    path.write_text(text.replace(marker, marker + "\n" + words * 15 + "\n", 1), encoding="utf-8")
+
+
 # --- the version itself ----------------------------------------------------
 
 
@@ -318,13 +329,237 @@ def test_release_entry_can_replace_the_title():
     assert "## 0.2.0 - 2026-09-05 - Summarising title" in released
 
 
+# --- the changelog: impact grading (Gitea #95) ------------------------------
+
+
+def test_bumps_block_with_all_medium_renders_flat_like_before():
+    section = version_mod._bumps_block([("medium", "First"), ("medium", "Second")])
+    assert version_mod._IMPACT_GROUP_RE.search(section) is None
+    assert "- First" in section and "- Second" in section
+
+
+def test_bumps_block_groups_by_impact_in_high_medium_low_order():
+    section = version_mod._bumps_block(
+        [("low", "Low one"), ("high", "High one"), ("medium", "Medium one")]
+    )
+    assert section.index("**High impact**") < section.index("**Medium impact**")
+    assert section.index("**Medium impact**") < section.index("**Low impact**")
+    assert "- High one" in section and "- Medium one" in section and "- Low one" in section
+
+
+def test_bumps_block_omits_empty_groups():
+    section = version_mod._bumps_block([("high", "Only one"), ("low", "Another")])
+    assert "**Medium impact**" not in section
+
+
+def test_bump_entries_round_trips_through_bumps_block():
+    """Round-trips the *grouping*, not the original chronological order: the
+    region is grouped by grade, so a reparse reads back grouped too."""
+    entries = [("high", "First"), ("low", "Second"), ("high", "Third")]
+    section = version_mod._bumps_block(entries)
+    assert version_mod.bump_entries(section) == [
+        ("high", "First"), ("high", "Third"), ("low", "Second"),
+    ]
+
+
+def test_bump_entries_reads_a_pre_impact_flat_region_as_all_medium():
+    section = f"{version_mod._BUMPS_OPEN}\n- Old style\n- Another\n{version_mod._BUMPS_CLOSE}"
+    assert version_mod.bump_entries(section) == [("medium", "Old style"), ("medium", "Another")]
+
+
+def test_summary_prose_is_the_text_between_the_bumps_region_and_the_first_changeset():
+    section = (
+        f"## 1.1.0 - 2026-09-12 - Title\n\n**Author:** Someone\n\n"
+        f"{version_mod._bumps_block([('medium', 'A')])}\n\n"
+        "This is the summary.\n\n### A\n\nDetail.\n"
+    )
+    assert version_mod.summary_prose(section).strip() == "This is the summary."
+
+
+def test_regrade_changes_several_indices_against_one_read():
+    text = CHANGES_HEADER + version_mod.insert_changes_entry(
+        "", Version(0, 2, 0, beta=1), "2026-09-01", "First", "Someone",
+    )
+    text = version_mod.insert_changes_entry(text, Version(0, 2, 0, beta=2), "2026-09-02", "Second", "Someone")
+    text = version_mod.insert_changes_entry(text, Version(0, 2, 0, beta=3), "2026-09-03", "Third", "Someone")
+    regraded = version_mod.regrade(text, Version(0, 2, 0, beta=3), {1: "high", 3: "low"})
+    section = version_mod.changes_section(regraded, Version(0, 2, 0, beta=3))
+    assert version_mod.bump_entries(section) == [
+        ("high", "First"), ("medium", "Second"), ("low", "Third"),
+    ]
+
+
+def test_regrade_refuses_an_out_of_range_index():
+    text = CHANGES_HEADER + version_mod.insert_changes_entry(
+        "", Version(0, 2, 0, beta=1), "2026-09-01", "Only", "Someone",
+    )
+    with pytest.raises(VersionError):
+        version_mod.regrade(text, Version(0, 2, 0, beta=1), {5: "high"})
+
+
+# --- version bump: --impact -------------------------------------------------
+
+
+def test_bump_without_impact_defaults_to_medium(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
+    section = version_mod.changes_section(changes, version_mod.read_version())
+    assert version_mod.bump_entries(section) == [("medium", "First bump")]
+
+
+def test_bump_with_impact_grades_the_bump_and_a_follow_up_regroups_the_list(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact="high", dry_run=False,
+    )
+    version_cmd.bump_command(
+        major=False, minor=False, patch=True, title="Second bump",
+        breaking=None, no_migration=None, migration_required=False, impact="low", dry_run=False,
+    )
+    changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
+    section = version_mod.changes_section(changes, version_mod.read_version())
+    assert version_mod.bump_entries(section) == [("high", "First bump"), ("low", "Second bump")]
+    assert "**High impact**" in section and "**Low impact**" in section
+
+
+def test_bump_refuses_an_unknown_impact(tree):
+    with pytest.raises(typer.Exit):
+        version_cmd.bump_command(
+            major=False, minor=True, patch=False, title="First bump",
+            breaking=None, no_migration=None, migration_required=False, impact="urgent", dry_run=False,
+        )
+    assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
+
+
+def test_breaking_line_sits_above_the_bumps_region(tree):
+    version_cmd.bump_command(
+        major=True, minor=False, patch=False, title="Breaking",
+        breaking="the feed moved", no_migration="kb/ untouched", migration_required=False,
+        impact=None, dry_run=False,
+    )
+    changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
+    assert changes.index(version_mod.BREAKING_CHANGE_MARKER) < changes.index(version_mod._BUMPS_OPEN)
+
+
+# --- version regrade --------------------------------------------------------
+
+
+def test_regrade_lists_the_running_candidates_bumps(tree, capsys):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact="high", dry_run=False,
+    )
+    version_cmd.regrade_command(indices=None, impact=None)
+    out = capsys.readouterr().out
+    assert "1. [high] First bump" in out
+
+
+def test_regrade_writes_the_new_impact_and_leaves_version_untouched(tree, capsys):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    version_cmd.bump_command(
+        major=False, minor=False, patch=True, title="Second bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    version_before = (tree / "VERSION").read_text(encoding="utf-8")
+    version_cmd.regrade_command(indices=[1, 2], impact="high")
+    assert (tree / "VERSION").read_text(encoding="utf-8") == version_before
+    changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
+    section = version_mod.changes_section(changes, version_mod.read_version())
+    assert version_mod.bump_entries(section) == [("high", "First bump"), ("high", "Second bump")]
+
+
+def test_regrade_refuses_without_impact(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    with pytest.raises(typer.Exit):
+        version_cmd.regrade_command(indices=[1], impact=None)
+
+
+def test_regrade_refuses_an_out_of_range_index_via_the_cli(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    with pytest.raises(typer.Exit):
+        version_cmd.regrade_command(indices=[9], impact="high")
+
+
+def test_regrade_fails_without_a_running_candidate(tree):
+    with pytest.raises(typer.Exit):
+        version_cmd.regrade_command(indices=None, impact=None)
+
+
+# --- version release: the summary requirement (Gitea #95) -------------------
+
+
+def test_release_refuses_two_bumps_with_no_summary(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    version_cmd.bump_command(
+        major=False, minor=False, patch=True, title="Second bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    with pytest.raises(typer.Exit):
+        version_cmd.release_command(title=None, dry_run=False)
+    assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0-beta.2"
+
+
+def test_release_dry_run_also_refuses_without_a_summary(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    version_cmd.bump_command(
+        major=False, minor=False, patch=True, title="Second bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    with pytest.raises(typer.Exit):
+        version_cmd.release_command(title=None, dry_run=True)
+
+
+def test_release_passes_with_two_bumps_once_a_summary_is_written(tree):
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="First bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    version_cmd.bump_command(
+        major=False, minor=False, patch=True, title="Second bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    _write_summary(tree)
+    version_cmd.release_command(title=None, dry_run=False)
+    assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0"
+
+
+def test_release_passes_with_a_single_bump_and_no_summary(tree):
+    """The one-bump exemption: there, the bump's own changeset already is the
+    summary. `test_release_fixes_version_and_the_changelog_heading` already
+    covers this shape; this test names the exemption explicitly."""
+    version_cmd.bump_command(
+        major=False, minor=True, patch=False, title="Only bump",
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
+    )
+    version_cmd.release_command(title=None, dry_run=False)
+    assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0"
+
+
 # --- version bump ----------------------------------------------------------
 
 
 def test_bump_writes_both_the_version_and_the_changelog_heading(tree):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="Something happened",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0-beta.1"
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
@@ -336,11 +571,11 @@ def test_bump_writes_both_the_version_and_the_changelog_heading(tree):
 def test_a_second_bump_continues_the_same_candidate_instead_of_opening_another(tree):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="First",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.bump_command(
         major=False, minor=False, patch=True, title="Second",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0-beta.2"
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
@@ -350,7 +585,7 @@ def test_a_second_bump_continues_the_same_candidate_instead_of_opening_another(t
 
 def test_bump_dry_run_writes_nothing(tree):
     version_cmd.bump_command(
-        major=False, minor=False, patch=True, title="Nope", breaking=None, no_migration=None, migration_required=False, dry_run=True
+        major=False, minor=False, patch=True, title="Nope", breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=True
     )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
     assert "1.0.1" not in (tree / "CHANGES.md").read_text(encoding="utf-8")
@@ -363,7 +598,7 @@ def test_bump_demands_exactly_one_part(tree, flags):
     major, minor, patch = flags
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
-            major=major, minor=minor, patch=patch, title="x", breaking=None, no_migration=None, migration_required=False, dry_run=False
+            major=major, minor=minor, patch=patch, title="x", breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False
         )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
 
@@ -371,7 +606,7 @@ def test_bump_demands_exactly_one_part(tree, flags):
 def test_bump_refuses_an_empty_title(tree):
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
-            major=False, minor=False, patch=True, title="   ", breaking=None, no_migration=None, migration_required=False, dry_run=False
+            major=False, minor=False, patch=True, title="   ", breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False
         )
 
 
@@ -384,7 +619,7 @@ def test_bump_refuses_when_version_and_changelog_disagree(tree):
     )
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
-            major=False, minor=False, patch=True, title="x", breaking=None, no_migration=None, migration_required=False, dry_run=False
+            major=False, minor=False, patch=True, title="x", breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False
         )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
 
@@ -398,7 +633,7 @@ def test_a_boundary_crossing_bump_without_a_migration_is_refused(tree):
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=True, minor=False, patch=False, title="Breaking",
-            breaking="the feed moved", no_migration=None, migration_required=False, dry_run=False,
+            breaking="the feed moved", no_migration=None, migration_required=False, impact=None, dry_run=False,
         )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
 
@@ -413,7 +648,7 @@ def test_a_boundary_crossing_bump_passes_with_a_migration_document(tree):
     )
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Breaking",
-        breaking="every page is retyped", no_migration=None, migration_required=False, dry_run=False,
+        breaking="every page is retyped", no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "2.0.0-beta.1"
 
@@ -430,11 +665,11 @@ def test_a_follow_up_bump_at_the_same_stage_need_not_repeat_breaking_or_migratio
     )
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Breaking",
-        breaking="every page is retyped", no_migration=None, migration_required=False, dry_run=False,
+        breaking="every page is retyped", no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Follow-up",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "2.0.0-beta.2"
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
@@ -446,7 +681,7 @@ def test_no_migration_records_the_reason_in_the_changelog(tree):
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Breaking",
         breaking="the release feed moved",
-        no_migration="no distributed instance exists yet", migration_required=False, dry_run=False,
+        no_migration="no distributed instance exists yet", migration_required=False, impact=None, dry_run=False,
     )
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
     assert version_mod.MIGRATION_NONE_MARKER in changes
@@ -458,7 +693,7 @@ def test_no_migration_is_refused_on_a_compatible_bump(tree):
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=False, minor=False, patch=True, title="Fix",
-            breaking=None, no_migration="not needed", migration_required=False, dry_run=False,
+            breaking=None, no_migration="not needed", migration_required=False, impact=None, dry_run=False,
         )
 
 
@@ -479,7 +714,7 @@ def test_migration_required_retracts_the_no_migration_line(tree):
     one after all has no other way to take that statement back."""
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Breaking",
-        breaking="the feed moved", no_migration="kb/ untouched", migration_required=False, dry_run=False,
+        breaking="the feed moved", no_migration="kb/ untouched", migration_required=False, impact=None, dry_run=False,
     )
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
     assert version_mod.MIGRATION_NONE_MARKER in changes
@@ -487,7 +722,7 @@ def test_migration_required_retracts_the_no_migration_line(tree):
     _migration_document(tree, "2.0.0")
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Turns out it migrates",
-        breaking=None, no_migration=None, migration_required=True, dry_run=False,
+        breaking=None, no_migration=None, migration_required=True, impact=None, dry_run=False,
     )
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
     assert version_mod.MIGRATION_NONE_MARKER not in changes
@@ -498,12 +733,12 @@ def test_migration_required_retracts_the_no_migration_line(tree):
 def test_migration_required_is_refused_without_a_migration_document(tree):
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Breaking",
-        breaking="the feed moved", no_migration="kb/ untouched", migration_required=False, dry_run=False,
+        breaking="the feed moved", no_migration="kb/ untouched", migration_required=False, impact=None, dry_run=False,
     )
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=True, minor=False, patch=False, title="Turns out it migrates",
-            breaking=None, no_migration=None, migration_required=True, dry_run=False,
+            breaking=None, no_migration=None, migration_required=True, impact=None, dry_run=False,
         )
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
     assert version_mod.MIGRATION_NONE_MARKER in changes  # unchanged
@@ -513,12 +748,12 @@ def test_migration_required_is_refused_with_no_no_migration_line_to_retract(tree
     _migration_document(tree, "2.0.0")
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Breaking",
-        breaking="the feed moved", no_migration=None, migration_required=False, dry_run=False,
+        breaking="the feed moved", no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=True, minor=False, patch=False, title="Nothing to retract",
-            breaking=None, no_migration=None, migration_required=True, dry_run=False,
+            breaking=None, no_migration=None, migration_required=True, impact=None, dry_run=False,
         )
 
 
@@ -527,7 +762,7 @@ def test_migration_required_is_refused_together_with_no_migration(tree):
         version_cmd.bump_command(
             major=True, minor=False, patch=False, title="Contradiction",
             breaking="the feed moved", no_migration="kb/ untouched",
-            migration_required=True, dry_run=False,
+            migration_required=True, impact=None, dry_run=False,
         )
 
 
@@ -536,7 +771,7 @@ def test_migration_required_is_refused_without_a_running_candidate(tree):
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=False, minor=False, patch=True, title="Fix",
-            breaking=None, no_migration=None, migration_required=True, dry_run=False,
+            breaking=None, no_migration=None, migration_required=True, impact=None, dry_run=False,
         )
 
 
@@ -564,7 +799,7 @@ def test_a_boundary_crossing_bump_without_breaking_is_refused(tree):
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=True, minor=False, patch=False, title="Renamed the feed",
-            breaking=None, no_migration="kb/ keeps its shape", migration_required=False, dry_run=False,
+            breaking=None, no_migration="kb/ keeps its shape", migration_required=False, impact=None, dry_run=False,
         )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
 
@@ -573,7 +808,7 @@ def test_breaking_records_what_stops_working_in_the_changelog(tree):
     version_cmd.bump_command(
         major=True, minor=False, patch=False, title="Renamed the feed",
         breaking="update_url points at a repo path that no longer exists",
-        no_migration="kb/ keeps its shape", migration_required=False, dry_run=False,
+        no_migration="kb/ keeps its shape", migration_required=False, impact=None, dry_run=False,
     )
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
     assert version_mod.BREAKING_CHANGE_MARKER in changes
@@ -590,7 +825,7 @@ def test_breaking_is_refused_on_a_compatible_bump(tree):
     with pytest.raises(typer.Exit):
         version_cmd.bump_command(
             major=False, minor=True, patch=False, title="New command",
-            breaking="nothing, really", no_migration=None, migration_required=False, dry_run=False,
+            breaking="nothing, really", no_migration=None, migration_required=False, impact=None, dry_run=False,
         )
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.0.0"
 
@@ -601,7 +836,7 @@ def test_breaking_is_refused_on_a_compatible_bump(tree):
 def test_release_fixes_version_and_the_changelog_heading(tree):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="First bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.release_command(title=None, dry_run=False)
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0"
@@ -614,12 +849,13 @@ def test_release_fixes_version_and_the_changelog_heading(tree):
 def test_release_can_replace_the_title(tree):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="First bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.bump_command(
         major=False, minor=False, patch=True, title="Second bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
+    _write_summary(tree)
     version_cmd.release_command(title="Summary of both bumps", dry_run=False)
     changes = (tree / "CHANGES.md").read_text(encoding="utf-8")
     assert "## 1.1.0 - " in changes
@@ -632,7 +868,7 @@ def test_release_can_replace_the_title(tree):
 def test_release_dry_run_writes_nothing(tree):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="First bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.release_command(title=None, dry_run=True)
     assert (tree / "VERSION").read_text(encoding="utf-8").strip() == "1.1.0-beta.1"
@@ -647,7 +883,7 @@ def test_release_refuses_when_version_is_already_a_release(tree):
 def test_release_refuses_when_version_and_changelog_disagree(tree):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="First bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     (tree / "VERSION").write_text("9.9.9-beta.1\n", encoding="utf-8")
     with pytest.raises(typer.Exit):
@@ -665,11 +901,11 @@ def test_notes_prints_the_entry_for_the_current_version(tree, capsys):
 def test_notes_prints_a_running_candidates_full_entry(tree, capsys):
     version_cmd.bump_command(
         major=False, minor=True, patch=False, title="First bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.bump_command(
         major=False, minor=False, patch=True, title="Second bump",
-        breaking=None, no_migration=None, migration_required=False, dry_run=False,
+        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
     )
     version_cmd.notes_command(version=None)
     out = capsys.readouterr().out

tools/chemenu/version.py

@@ -459,20 +459,125 @@ def changes_section(text: str, version: Version) -> Optional[str]:
     return None
 
 
-def _bumps_block(titles: list[str]) -> str:
+# Gitea #95: a long-running candidate's bump list grew to 20 chronological,
-    lines = "\n".join(f"- {title}" for title in titles)
+# ungraded titles (v5.0.0, ~1440 lines) - unreadable as a release announcement.
+# Grading it at bump time, and letting a session regrade it before release,
+# is the fix; see instructions/dev/version-parts.md § The candidate model.
+IMPACT_LEVELS = ("high", "medium", "low")
+DEFAULT_IMPACT = "medium"
+_IMPACT_GROUP_RE = re.compile(r"^\*\*(High|Medium|Low) impact\*\*$", re.MULTILINE)
+
+
+def _bumps_block(entries: list[tuple[str, str]]) -> str:
+    """Render the bumps region from `(impact, title)` pairs.
+
+    Grouped under a `**High/Medium/Low impact**` heading, in that order, each
+    present only if it holds at least one title. **Except** when every entry
+    is `medium` (the default, and the only grade that existed before this):
+    rendered flat, with no heading at all, exactly as `version bump` always
+    wrote it. That keeps a single-bump patch entry, and every entry a build
+    that predates `--impact` ever wrote, byte-identical to what it was.
+    """
+    if all(impact == DEFAULT_IMPACT for impact, _ in entries):
+        lines = "\n".join(f"- {title}" for _, title in entries)
         return f"{_BUMPS_OPEN}\n{lines}\n{_BUMPS_CLOSE}"
+    groups: dict[str, list[str]] = {level: [] for level in IMPACT_LEVELS}
+    for impact, title in entries:
+        groups[impact].append(title)
+    rendered = [
+        f"**{level.capitalize()} impact**\n" + "\n".join(f"- {title}" for title in groups[level])
+        for level in IMPACT_LEVELS
+        if groups[level]
+    ]
+    return f"{_BUMPS_OPEN}\n" + "\n\n".join(rendered) + f"\n{_BUMPS_CLOSE}"
 
 
-def _bump_titles(section: str) -> list[str]:
+def bump_entries(section: str) -> list[tuple[str, str]]:
+    """The bumps region parsed back into `(impact, title)` pairs, in rendered
+    order - the addressing `version regrade` and `version_cmd.release_command`
+    use.
+
+    A `**<Grade> impact**` heading sets the running grade for the `- ` lines
+    beneath it; a `- ` line with none above it - the shape every region had
+    before `--impact` existed, and the flat shape `_bumps_block` still writes
+    when every grade is `medium` - reads as `medium`. That is what makes an
+    old region parse the same as a new one that happens to grade everything
+    the same way.
+    """
     match = _BUMPS_RE.search(section)
     if not match:
         return []
-    return [
+    entries: list[tuple[str, str]] = []
-        line[2:].strip()
+    current = DEFAULT_IMPACT
-        for line in match.group(1).strip("\n").splitlines()
+    for line in match.group(1).strip("\n").splitlines():
-        if line.strip().startswith("- ")
+        stripped = line.strip()
+        heading_match = _IMPACT_GROUP_RE.match(stripped)
+        if heading_match:
+            current = heading_match.group(1).lower()
+            continue
+        if stripped.startswith("- "):
+            entries.append((current, stripped[2:].strip()))
+    return entries
+
+
+# The free-form paragraph `version release` requires above the changesets once
+# a candidate collected more than one bump - see `summary_prose` and
+# `version_cmd.release_command`. A number, not a quality judgement: it catches
+# the empty and the one-line "TODO" case, nothing subtler.
+SUMMARY_MIN_CHARS = 200
+_CHANGESET_HEADING_RE = re.compile(r"^### ", re.MULTILINE)
+
+
+def summary_prose(section: str) -> str:
+    """The text between the bumps region (or, for an entry with none, the
+    heading) and the first `### <bump title>` changeset heading - the
+    candidate's own summary of what it did, as opposed to the per-bump detail
+    below it.
+    """
+    close = section.find(_BUMPS_CLOSE)
+    if close != -1:
+        start = close + len(_BUMPS_CLOSE)
+    else:
+        heading_match = _CHANGES_ENTRY_RE.match(section)
+        start = heading_match.end() if heading_match else 0
+    heading = _CHANGESET_HEADING_RE.search(section, start)
+    end = heading.start() if heading else len(section)
+    return section[start:end]
+
+
+def regrade(text: str, version: "Version", updates: dict[int, str]) -> str:
+    """Change the impact grade of one or more of the topmost entry's bump
+    titles, addressed by their 1-based position in `bump_entries`'s rendered
+    order.
+
+    All of `updates` are read against a **single** parse of the region, so
+    `{3: "high", 7: "high"}` in one call means "regrade these two against
+    today's list" - not "regrade #3, re-render, then regrade #7 against
+    whatever that produced". `version_cmd.regrade_command` is the only
+    caller; `version` must already equal the entry it addresses (the same
+    VERSION/newest-entry agreement every other write here requires).
+    """
+    start, end = _entry_span(text)
+    section = text[start:end]
+    heading_match = _CHANGES_ENTRY_RE.match(section)
+    if not heading_match or Version.parse(heading_match.group(1)) != version:
+        raise VersionError(f"{CHANGES_FILENAME}'s topmost entry does not name {version}")
+
+    entries = bump_entries(section)
+    if not entries:
+        raise VersionError(f"{version}'s {CHANGES_FILENAME} entry has no bump list to regrade")
+    out_of_range = sorted(i for i in updates if i < 1 or i > len(entries))
+    if out_of_range:
+        raise VersionError(
+            f"index/indices out of range (1-{len(entries)}): {', '.join(map(str, out_of_range))}"
+        )
+
+    new_entries = [
+        (updates.get(position, impact), title)
+        for position, (impact, title) in enumerate(entries, start=1)
     ]
+    new_section = _BUMPS_RE.sub(lambda _m: _bumps_block(new_entries), section, count=1)
+    return text[:start] + new_section + text[end:]
 
 
 def _set_marker_line(section: str, marker: str, line: str) -> str:
@@ -481,17 +586,17 @@ def _set_marker_line(section: str, marker: str, line: str) -> str:
     Used for the breaking-change and no-migration lines, which - unlike the
     bumps list - are not accumulated: a later bump that repeats `--breaking`
     restates it rather than growing a list nobody would read as history.
+    Anchored just above the bumps region (not below it, as before Gitea #95):
+    with a graded, potentially 30-line list, the line an operator most needs
+    to act on stayed the deepest thing in the entry otherwise.
     """
     pattern = re.compile(rf"^{re.escape(marker)}.*$", re.MULTILINE)
     if pattern.search(section):
         return pattern.sub(line, section, count=1)
-    anchor = section.find(_BUMPS_CLOSE)
+    anchor = section.find(_BUMPS_OPEN)
     if anchor != -1:
-        insert_at = section.find("\n", anchor)
+        return section[:anchor] + f"{line}\n\n" + section[anchor:]
-        insert_at = insert_at + 1 if insert_at != -1 else len(section)
+    return section.rstrip() + f"\n\n{line}\n"
-    else:
-        insert_at = len(section)
-    return section[:insert_at] + f"\n{line}\n" + section[insert_at:]
 
 
 def _clear_marker_line(section: str, marker: str) -> str:
@@ -525,10 +630,12 @@ def _update_open_candidate(
     breaking_reason: Optional[str],
     no_migration_reason: Optional[str],
     migration_required: bool = False,
+    impact: str = DEFAULT_IMPACT,
 ) -> str:
     """Move the topmost entry's heading to `version`/`date`/`title`, append
-    `title` to its machine-managed bump list, and set the breaking/no-migration
+    `(impact, title)` to its machine-managed bump list, and set the
-    lines only where this call supplies them - see `insert_changes_entry`.
+    breaking/no-migration lines only where this call supplies them - see
+    `insert_changes_entry`.
 
     `migration_required` retracts an earlier `--no-migration` line instead of
     setting one - the two are mutually exclusive on a single bump, enforced by
@@ -541,7 +648,9 @@ def _update_open_candidate(
         raise VersionError(f"{CHANGES_FILENAME}'s topmost entry has no parseable version heading")
     section = f"## {version} - {date} - {title}" + section[heading_match.end():]
 
-    section = _BUMPS_RE.sub(lambda _m: _bumps_block(_bump_titles(section) + [title]), section, count=1)
+    section = _BUMPS_RE.sub(
+        lambda _m: _bumps_block(bump_entries(section) + [(impact, title)]), section, count=1
+    )
 
     if breaking_reason:
         section = _set_marker_line(section, BREAKING_CHANGE_MARKER, f"{BREAKING_CHANGE_MARKER} {breaking_reason}")
@@ -562,6 +671,7 @@ def insert_changes_entry(
     no_migration_reason: Optional[str] = None,
     breaking_reason: Optional[str] = None,
     migration_required: bool = False,
+    impact: str = DEFAULT_IMPACT,
 ) -> str:
     """Open a new entry above the newest existing one, or - when the topmost
     entry is still an open candidate (a pre-release heading) - update that
@@ -573,14 +683,17 @@ def insert_changes_entry(
     the topmost heading still a pre-release" the right test for "is a
     candidate still open" here.
 
-    A fresh entry gets the skeleton only: heading, date, author, the
+    A fresh entry gets the skeleton only: heading, date, author, - when a
-    machine-managed bump-title list (started with this one title, for a
+    compatibility boundary is crossed - the line saying what breaks, plus the
-    candidate), and - when a compatibility boundary is crossed - the line
+    line saying no content has to change where that applies, and then the
-    saying what breaks, plus the line saying no content has to change where
+    machine-managed bump list (started with this one `(impact, title)` pair,
-    that applies. The break comes first: it is what an operator reading the
+    for a candidate). The break comes first, above the bump list rather than
-    release notes has to act on, and the migration line only qualifies it. The
+    below it (Gitea #95): it is what an operator reading the release notes has
-    entry's actual prose is written afterwards by whoever made the change,
+    to act on, the migration line only qualifies it, and neither should sit
-    which is also why `bump` refuses to invent a title.
+    beneath a list that can run to dozens of graded entries. The entry's
+    actual prose - the release summary, and each bump's own changeset - is
+    written afterwards by whoever made the change, which is also why `bump`
+    refuses to invent a title.
 
     `migration_required` only has anything to retract on an already-open
     candidate, so a fresh entry ignores it - there is no earlier
@@ -591,16 +704,16 @@ def insert_changes_entry(
         return _update_open_candidate(
             text, version, date, title,
             breaking_reason=breaking_reason, no_migration_reason=no_migration_reason,
-            migration_required=migration_required,
+            migration_required=migration_required, impact=impact,
         )
 
     lines = [f"## {version} - {date} - {title}", "", f"**Author:** {author}", ""]
-    if version.is_prerelease:
-        lines += [_bumps_block([title]), ""]
     if breaking_reason:
         lines += [f"{BREAKING_CHANGE_MARKER} {breaking_reason}", ""]
     if no_migration_reason:
         lines += [f"{MIGRATION_NONE_MARKER} - {no_migration_reason}", ""]
+    if version.is_prerelease:
+        lines += [_bumps_block([(impact, title)]), ""]
     entry = "\n".join(lines) + "\n---\n\n"
     anchor = re.search(r"^## ", text, re.MULTILINE)
     if anchor: