[tony]

Why

libtmux-java publishes ten Maven modules, libtmux, libtmux-mcp, libtmux-workspace, libtmux-workspace-cli, libtmux-kotlin, libtmux-scala, libtmux-scala-cats, libtmux-scala-ox, libtmux-jackson and libtmux-junit5, but kept one CHANGELOG.md for all of them, so a reader of one module had to read the others' history to find their own, and no jar carried a changelog. The maintainer asked for one per published package and said a main changelog beside a changelog for each package is fine. Once each module has a file, nothing noticed a module losing it or a jar going out without it, so the change also extends the release check.

Modelled on libtmux-ts #146.

What

• Splits the history into a changelog per module, every entry moved verbatim with its PR and issue links, under its original release and section heading: libtmux, libtmux-mcp, libtmux-workspace, libtmux-workspace-cli, libtmux-kotlin, libtmux-scala, libtmux-scala-cats, libtmux-scala-ox, libtmux-jackson, libtmux-junit5. The root CHANGELOG.md keeps what spans modules. Each file keeps the release headings, dates and the Unreleased heading, with an introduction naming its module.
• Ships each module's file in its jar: libtmux.publication.gradle.kts copies the CHANGELOG.md beside a module's build file into META-INF/libtmux/<module>/, next to the artwork the convention already puts there. A Maven POM has no field for release notes, so the jar is the carrier. libtmux-bom is a platform with no jar and no changelog; its entries are in the root file.
• Extends the staged-release check, tools/verify-staged-release.sh, to refuse a staged jar that does not hold its module's changelog, or holds one that does not open with Notable changes to and the module's name. A Scala artifact's id ends in _3; the check strips it to find the module.
• Adds a guard to tools/ci/check.py, which the tmux-matrix plan job already runs on every pull request: every published module keeps a CHANGELOG.md that opens with its own name and holds a ## Unreleased heading outside a code fence, its README links it, and the publication convention still ships it with a from(...) line that is not commented out. The published modules are read from settings.gradle.kts, so a module added later without a changelog is caught.
• Links each module's changelog from its README, and says in WRITING.md, CONTRIBUTING.md, RELEASING.md and AGENTS.md which file an entry goes in and that the tag commit dates every changelog.

Nothing lost

An entry is a top-level bullet with its nested content, or a blank-line separated paragraph. A script parsed the old file at e227c943 and the eleven new files separately and required every old entry to appear in exactly one new file, under its original release and section headings, with nothing added. The one difference it allows is the ../ that a relative link needs once its entry sits one directory down, which 28 entries gained.

File	Entries	PR and issue references
old CHANGELOG.md at e227c943	288	209
new CHANGELOG.md	69	28
new libtmux/CHANGELOG.md	129	122
new libtmux-mcp/CHANGELOG.md	55	28
new libtmux-workspace/CHANGELOG.md	4	4
new libtmux-workspace-cli/CHANGELOG.md	8	9
new libtmux-kotlin/CHANGELOG.md	12	10
new libtmux-scala/CHANGELOG.md	1	1
new libtmux-scala-cats/CHANGELOG.md	2	2
new libtmux-scala-ox/CHANGELOG.md	0	0
new libtmux-jackson/CHANGELOG.md	0	0
new libtmux-junit5/CHANGELOG.md	8	5
new total	288	209

Dropping an entry, duplicating one into a second file, changing a single word, adding an entry, or swapping two release headings makes the script fail, so it is capable of failing. The script is not in this change: it compares against one old commit, so as a gate it would go stale at the next changelog edit.

Judgement calls

• The old file grouped entries by Added, Changed, Fixed and so on, not by module, so each entry went to the module it changes. An entry that names no module but changes a core API is a libtmux entry. The early alphas' libtmux-mcp entries (tmux_run, tmux_whoami, the safety tiers, the toolsets) rarely name the module, and I read each one to place it; the fixtures TmuxExtension, NamedServerFixture and FakeTmux are libtmux-junit5.
• An entry that changes two modules stays in the root file, because each entry lives in exactly one: a core call together with the MCP tool that wraps it, ServerConfig.force256Colors together with tmux-workspace load -2, the sealed exception tree that also changes libtmux-jackson, the Scala and Ox LiveView entry, and FilterModel.fieldNames, which is a libtmux-jackson class that the MCP server reads. So do documentation, CI, tests, build and release tooling, libtmux-bom and the release summaries, whichever module they concern.
• libtmux-jackson and libtmux-scala-ox have no entry of their own in the old file. Their files keep every release heading from the module's first release and say No entries for `libtmux-jackson`. under each. The line says "no entries" rather than "no change" because the old file did not record every source change in the early releases.
• A module file starts at the release that first shipped the module: libtmux-workspace-cli at 0.0.1-alpha.16, and the three Scala modules at 0.0.1-alpha.13, the first release whose entries name them, although the first tag with their directories is alpha.15.
• The shared status notice, "the changelog marks each break", is kept word for word in the root README and in every changelog introduction, as WRITING.md requires, so the root README does not name the module changelogs in it; the paragraph below it and the Documentation section do.
• A relative link in a moved entry (28 of them, almost all into MIGRATION.md) would lead nowhere from the module directory, and DocumentationFactsTest fails on a link that does not resolve, so each gained ../. That is the only change to entry text, and the script checks it.

The check

The staged-release script is what the release rehearsal job in ci.yml runs on a signed staging, so the rule lives there. test_staged_release.py stages a small repository with a throwaway signing key, so every other rule of the script passes, and breaks one jar at a time: the unbroken staging passes, a Scala jar with no changelog is refused by its module name and not its artifact id, and a jar holding another module's changelog is refused. With the new block removed from the script, the two refusals fail and the unbroken staging still passes. The test skips where gpg cannot make a key.

The guard has eight tests in test_check.py, each breaking a copy of the tree: a deleted changelog, a new published module without one, another module's changelog pasted over this one, a missing Unreleased heading and one inside a code fence, a README that does not link its changelog, and a publication convention that stops shipping it. With the guard switched off, seven of the eight fail; the eighth, that the guard finds the ten jars and not the BOM, tests discovery. test_staged_release is added to the plan job's unittest line in tmux-matrix.yml, beside test_check.

Verification

Run on the final tree, through the host's heavy-job wrapper: python3 -m unittest tools.ci.test_check tools.ci.test_staged_release tools.ci.test_plan tools.ci.test_tmux_ref (83 tests, and test_staged_release fails rather than skips when CI is set and gpg cannot make a key) and python3 -m tools.ci.check; ./gradlew :docs:test --tests io.github.libtmux.docs.DocumentationFactsTest, which resolves every Markdown link in the repository, with the new changelogs in place; and processResources for libtmux, libtmux-mcp and libtmux-scala, whose built jars list META-INF/libtmux/<module>/CHANGELOG.md.

Not run locally: a full staging with a signing key (publishAllPublicationsToStagingRepository), which CI does in its release rehearsal, and the real-tmux suites.

Not for merging yet: master stays held until the docs pin wave finishes.

Closes #122.