chemenu/raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md

Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session

Source: Claude Code session (claude-sonnet-5), chemenu workspace Collected: 2026-09-02 Participant: Torben Nehmer Fidelity: faithful summary transcript, not a verbatim log. The user's instructions and clarifications are quoted verbatim; the agent's own reasoning and file-reading steps are paraphrased; tool output blocks (docs verify, pytest, version bump --dry-run, the Mass-Update Gate refusal) are real, copied from the actual run, not reconstructed. No second-hand material - no subagent was used. No credentials appeared. Single topic, not cut.

Closes Gitea issue #26 (already closed in-session) with 2.5.0. Commit 31662dc on main. Covers picking the version part for a stack change, and adding a user-approval gate for breaking changes to stack-dev.

Turn 1 - /stack-dev kümmere dich um #26

The user invoked the stack-dev skill with the argument kümmere dich um #26. The agent read issue #26 via gitea-mcp (torben/chemenu#26, no comments yet).

The issue's own account (quoted from its body, since it is the source of the whole session): the stack's documentation conflated two questions when choosing a version bump part - "Muss der Korpus migriert werden?" and "Ist der Wechsel rückwärtskompatibel?" - and every place an agent would consult before a bump stated only the first:

Ort	Wortlaut
instructions/dev/stack-dev/SKILL.md, Schritt 3	--major ⇔ "Existing content must be migrated"
tools/chemenu/version.py, module docstring	"from 1.0.0 on the same rule reads as the familiar 'MAJOR means migration'"
INSTALL.md § Version und Updates	"ab 1.0.0 liest sich dieselbe Regel als das gewohnte 'MAJOR heißt Migration'"

Only version bump --help had it right ("A bump that crosses the compatibility boundary additionally requires a migration document ... or --no-migration") - the one place read only after the decision is already made.

The issue's worked example was the 2.0.0 rebranding (torben/llm-wiki-test1 → torben/chemenu): no page in kb/ changed, so the first attempt at that bump was 1.9.0. Three things broke anyway - the release-feed URL baked into every existing instance's .wikitool-release.json (unrepairable by hand, per invariant 1), the release artefact's filename, and the Python package's import name. The correct bump was --major --no-migration. The issue's "Was 'fertig' heißt" checklist asked for: rewording the three prose locations to lead with compatibility rather than migration, a decision aid enumerating which kinds of break force MAJOR even with kb/ untouched, and a check that the three locations do not end up contradicting each other (invariant 8). It explicitly scoped out teaching docs verify to judge whether a bump chose the right part - "das ist eine Urteilsfrage und kein hartes Orakel."

The agent read the three prose locations plus tools/chemenu/commands/version_cmd.py (the existing --no-migration enforcement) and docs_verify.py (check_migration_for_boundary), to scope the fix before writing anything.

Turn 2 - scope questions, then the user's clarification

Before writing, the agent asked two AskUserQuestion questions:

1. Whether the "Breaking Change" marker and approval requirement should be prose-only or also enforced in the tool. Options offered: "Prosa + Marker im Code (Empfehlung)" vs. "Nur Prosa". User picked the enforced option ("Prosa + Marker im Code (Empfehlung)") - a --breaking flag on version bump, checked by docs verify, on the reasoning that a pure-prose rule is exactly what drifted in the first place.
2. Whether the pre-bump approval step should read like one of the codebase's actual gates (instructions/gates.md language: "anhalten ... auf ausdrückliche Freigabe warten") or as a softer "Decision points" entry. User picked the softer framing ("Als Entscheidungspunkt")
   • explicitly not gate language, to avoid diluting the weight of the three real, code-enforced gates (Mass-Update, Publish-Remote, Iteration Budget) by association.

The user then added the clarification that drove the rest of the session, quoted in full:

"genaue nomenklatur für major version change: die neue version ist kein drop-in replacement. Sobald irgendwie Hand angelegt werden muss, sei es durch den user oder durch ein Migrationsscript, ist es ein major version change. selbiges gilt, wenn ein update nicht rückgängig gemacht werden kann (Szenario: User aktualisiert den Stack von vA nach vB, vB hat beim User ein Problem, kann jetzt vA nicht mehr einfach so als Downgrade installiert werden, ist es ein breaking change) in allen Fällen muss bei einem Major version change ein "Breaking Change" vermerkt werden. breaking changes sind damit teuer. passe stack-dev so an, dass in diesen Fällen zwingend der user informiert, Alternativen aufgezeigt und eine freigabe eingeholt wird."

This sharpened the issue's "compatibility" question into a concrete two-sided test - forward (can the new version be copied over with zero hand-work, by user or script) and backward (can the old version still be reinstalled afterwards) - and made explicit that either half failing, independent of kb/, is what MAJOR actually means.

Turn 3 - what was written

instructions/dev/version-parts.md (new). The single source for the rule. Structure: the two-sided drop-in test (step 1); a catalogue of breaks that cross the boundary with kb/ untouched - update path, release-artefact name, package import name, a renamed command/flag/envvar, the shape of a machine-read file like .wikitool-kb.json (step 2); the plain compatible-part table for patch/minor (step 3); the mandatory stop-and-inform-the-user step before any boundary-crossing bump, with three named alternatives (avoid via a compatibility shim, defer and batch with the next crossing, split into a compatible half now and a deprecated-then-removed half later) plus a recommendation (step 4); --breaking usage (step 5); the pre-existing migration-document-or---no-migration step, now explicitly independent of compatibility (step 6); writing the entry body (step 7). Closes with the 2.0.0 case study as the worked example, matching the issue's own account.

Placed under instructions/dev/ (not linked from any distributed artifact) because tools/wikitool dist export prunes that directory wholesale - the agent's first draft linked to it from tools/CONTRACT.md and the version.py docstring, which tools/wikitool instructions verify correctly rejected:

ERROR Instruction layer issues:
  - version-parts.md: lives under instructions/dev/ but is referenced from
outside it and outside a dist:strip block - `dist export` removes
instructions/dev/ wholesale, so that reference would dangle in a distributed
instance. Remove the reference, or wrap it in a <!-- dist:strip-start/end -->
block if it belongs only to this dev instance.

Rejected approach: wrapping the reference in <!-- dist:strip-start/end --> markers so it would still resolve in this repo. Not used - the agent instead rewrote the three shipped locations (tools/CONTRACT.md, version.py docstring, version_cmd.py docstring) to state the short form of the rule standalone, with no pointer to the dev-only file, since a shipped instance never has it to point to.

instructions/dev/stack-dev/SKILL.md. Step 3's table changed from "Existing content must be migrated → --major" to "Not a drop-in replacement ... → --major", with a pointer to version-parts.md for the full test and catalogue. A new "Decision points" entry: if a change turns out not to be a drop-in replacement, stop - do not bump across the boundary on the session's own initiative; show the user the concrete break, what each instance must do, and the three alternatives from version-parts.md step 4, then wait for a go-ahead. Written in the softer "Decision points" register per the user's second answer above, not gate language.

tools/chemenu/version.py. Module docstring reworded: "MAJOR means migration" → "MAJOR breaks", with a new paragraph stating the two questions are independent and naming both markers. New constant BREAKING_CHANGE_MARKER = "**Breaking Change:**", alongside the existing MIGRATION_NONE_MARKER. insert_changes_entry() gained a breaking_reason parameter, writing the **Breaking Change:** line before the migration line - the break is what an operator acts on first.

tools/chemenu/commands/version_cmd.py. bump gained --breaking TEXT. Refused on a non-boundary-crossing bump; required on a boundary-crossing one, with a refusal message that also second-guesses the part choice itself: "If that sentence is hard to write because nothing actually breaks - no hand-work on update, and the old version can still be put back - then the bump is probably not --major." Verified live:

$ tools/wikitool version bump --major --title "smoke" --dry-run
ERROR 2.4.1 -> 3.0.0 crosses the compatibility boundary, so it is not a drop-in
replacement - re-run with --breaking "<what stops working, and what an instance
must do about it>".
If that sentence is hard to write because nothing actually breaks - no
hand-work on update, and the old version can still be put back - then the
bump is probably not --major.

$ tools/wikitool version bump --minor --title "smoke" --breaking "x" --dry-run
ERROR --breaking only applies to a bump that crosses the compatibility boundary;
2.4.1 -> 2.5.0 does not.

tools/chemenu/commands/docs_verify.py. New check_breaking_change_for_boundary(), independent of the existing check_migration_for_boundary() on purpose - the two check different things (did the corpus move vs. was the operator told the swap isn't drop-in), and a crossing with kb/ untouched can satisfy the first while failing the second. Wired into verify() alongside the existing check.

Tests. test_version_cmd.py: nine existing calls updated for the new breaking= parameter, plus three new tests (test_a_boundary_crossing_bump_without_breaking_is_refused, test_breaking_records_what_stops_working_in_the_changelog - including the ordering assertion that BREAKING_CHANGE_MARKER precedes MIGRATION_NONE_MARKER in the rendered entry - test_breaking_is_refused_on_a_compatible_bump). test_docs_verify.py: four new tests mirroring the existing migration-boundary tests but for the breaking-change marker. Full suite: 806 passed.

tools/CONTRACT.md and INSTALL.md. Both reworded to lead with the drop-in question and treat migration as the second, independent one; INSTALL.md additionally tells the reader which two lines to look for in release notes (Breaking Change: and Migration:) before applying an update.

CHANGES.md. New 2.5.0 entry written after the bump, body filled in by the agent (the tool leaves it empty by design) - includes the "what deliberately did not change" note that docs verify still does not judge whether the chosen part was correct, matching the issue's explicit scope-out.

Turn 4 - publish, twice

tools/wikitool version bump --minor --title "..." was run first (11 changed files, drop-in in both directions - the new requirement only binds the next boundary crossing, not retroactively). tools/wikitool publish --message "..." then hit the Mass-Update Gate (11 counted files ≥ threshold 10):

NEEDS USER CLEARANCE Mass-Update Gate: this publish would commit and push 11
counted files (>= threshold 10) to origin/main. ...

Per the gate's own instructions, the agent reproduced the full file-by-area breakdown and the --confirm <token> line in its reply and ran nothing further that turn. The user replied "freigegeben" for both the earlier publish authorization ("publish ist freigegeben") and, in a separate turn, this specific token. The agent then ran tools/wikitool publish --confirm 95ae372d5677 --message '...', which pushed commit 31662dc to origin/main, and verified git rev-parse HEAD origin/main matched afterward.

Turn 5 - issue closeout and this capture

The user asked to update issue #26 "wie vorgeschlagen" (per the agent's own end-of-turn suggestion), run instructions/capture-session.md, and in the same pass correct kb/entities/tools/wikitool.md. The agent posted a comment on #26 summarizing what shipped (including the parts that went beyond the issue's own checklist - the --breaking flag and the second docs verify check, added because plain prose was judged likely to drift again) and closed the issue. This transcript and the kb/ correction are the remaining two steps of that request.

Outcome

Version	2.4.1 → 2.5.0 (--minor: new capability, still drop-in both directions)
Commit	31662dc on main, pushed to origin
Files changed	11 (+432/-33): instructions/dev/version-parts.md (new), instructions/dev/stack-dev/SKILL.md, tools/CONTRACT.md, tools/chemenu/version.py, tools/chemenu/commands/version_cmd.py, tools/chemenu/commands/docs_verify.py, tools/chemenu/tests/test_version_cmd.py, tools/chemenu/tests/test_docs_verify.py, CHANGES.md, INSTALL.md, VERSION
Tests	806 passed (tools/chemenu/tests/), including 6 new
Verification	tools/wikitool docs verify OK, tools/wikitool instructions verify OK (17 instructions, 6 skills, 12 published copies match), tools/wikitool doctor clean (only the expected WIKITOOL_SESSION_ID WARN)
Issues	#26 closed, comment torben/chemenu#26 (issuecomment-474)
CI	Not yet observed in this session - a VERSION move on main triggers a tagged release per .gitea/workflows/release.yml; not polled