Adopt Towncrier changelog fragments (#3609)

Author: eric-heiden

.claude/skills/release-audit/SKILL.md

@@ -62,7 +62,7 @@ These are noted here so Claude can pattern-match when reading commits, but the s
 
 - `.github/**`, `.pre-commit-config.yaml`, `uv.lock`, `.python-version` — infrastructure, not user-facing.
 - `asv.conf.json`, `asv/**`, root-level `_bench_*.py` — benchmark harness.
-- `docs/**`, root-level `*.md`, `CHANGELOG.md` — documentation.
+- `docs/**`, root-level `*.md`, `CHANGELOG.md`, `changelog/**` — documentation.
 - `newton/examples/**` — example scripts. New files here are user-facing (a new example is a release-notable addition). Changes to existing examples are typically not release-notable unless they change the example's registered name or behavior.
 - `newton/_src/**` other than the solver / sim / math / geometry paths above — internal Python implementation.
 - `pyproject.toml`, `uv.lock`, and files matched by `project.license-files` — dependency and license-audit inputs. New external dependency names, direct requirement scope changes, new resolved package names, and notice-file changes belong in "Dependency & License Audit". Version bumps are not release-notable on their own; dependency changes may also belong in "Behavioral & Support Changes" if a user-visible pin moves (e.g., `mujoco-warp ~=3.7.0`).

.claude/skills/release-audit/references/classification-rules.md

@@ -56,7 +56,7 @@ For entry "Add support for Gaussian splats (GH-NNNN)", fetch commits tagged `GH-
 
 Don't flag if:
 - Commits touch `newton/_src/geometry/**` or `newton/_src/sim/builder.py` for a geometry-addition entry → topic matches.
-- Commits touch `docs/**` and the entry is in the Documentation section → topic matches.
+- Commits touch `docs/**` and the `Added` or `Changed` entry describes that documentation → topic matches.
 - Commits touch `newton/_src/solvers/**` for a solver-capability entry → topic matches.
 
 **Tier-2 heuristic (only if `gh` CLI is installed + authenticated):**
@@ -114,7 +114,10 @@ Before flagging, cross-check against existing sibling symbols in the same module
 
 **Err on "mention, don't block"**: flagging should raise a question for human review, not gate the report. The audit appendix shows flagged entries and a one-line reason; a human decides.
 
-**Don't auto-rewrite**: Claude flags the entry, never modifies it. The release manager updates CHANGELOG.md manually.
+**Don't auto-rewrite**: Claude flags the entry, never modifies it. Before the
+Towncrier build, the release manager updates pending fragments during changelog
+maintenance; after release, corrections to dated history require explicit
+maintainer approval.
 
 **Prefer false positives over false negatives**: a flag that turns out to be fine costs a 5-second eyeball. A missed wrong-ref or jargon-leak ships to users.
 

.claude/skills/release-audit/references/language-review-examples.md

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 The Newton Developers
+# SPDX-License-Identifier: Apache-2.0
+
+"""Safely remove a temporary Newton release-audit report."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import tempfile
+from pathlib import Path
+
+_REPORT_NAME = re.compile(r"newton-[A-Za-z0-9][A-Za-z0-9.+-]*-(?:prerelease|rc|retrospective)-report\.md")
+
+
+def cleanup_report(path: Path, *, temporary_directory: Path | None = None) -> None:
+    """Remove an allowed report directly beneath the temporary directory."""
+    temporary_root = (temporary_directory or Path(tempfile.gettempdir())).resolve()
+    if path.is_symlink():
+        raise ValueError("report path must not be a symlink")
+    candidate = path.resolve()
+    if candidate.parent != temporary_root:
+        raise ValueError(f"report must be directly beneath {temporary_root}")
+    if _REPORT_NAME.fullmatch(candidate.name) is None:
+        raise ValueError(f"not an allowed Newton report filename: {candidate.name}")
+    path.unlink(missing_ok=True)
+
+
+def main() -> None:
+    """Run the report cleanup command."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("path", type=Path)
+    args = parser.parse_args()
+    try:
+        cleanup_report(args.path)
+    except ValueError as error:
+        parser.error(str(error))
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/release-audit/scripts/cleanup_report.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 The Newton Developers
+# SPDX-License-Identifier: Apache-2.0
+
+"""Test safe release-audit report cleanup."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from cleanup_report import cleanup_report
+
+
+class CleanupReportTest(unittest.TestCase):
+    def test_removes_allowed_report(self):
+        """Remove an allowed report from the temporary root."""
+        with tempfile.TemporaryDirectory() as directory:
+            temporary_root = Path(directory)
+            report = temporary_root / "newton-1.5.0-prerelease-report.md"
+            report.write_text("report\n", encoding="utf-8")
+
+            cleanup_report(report, temporary_directory=temporary_root)
+
+            self.assertFalse(report.exists())
+
+    def test_rejects_unexpected_filename(self):
+        """Reject a file that is not a Newton release-audit report."""
+        with tempfile.TemporaryDirectory() as directory:
+            temporary_root = Path(directory)
+            report = temporary_root / "unrelated.md"
+            report.write_text("keep\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(ValueError, "not an allowed"):
+                cleanup_report(report, temporary_directory=temporary_root)
+
+            self.assertTrue(report.exists())
+
+    def test_rejects_nested_path(self):
+        """Reject an allowed filename outside the temporary root."""
+        with tempfile.TemporaryDirectory() as directory:
+            temporary_root = Path(directory)
+            nested = temporary_root / "nested"
+            nested.mkdir()
+            report = nested / "newton-1.5.0-rc-report.md"
+            report.write_text("keep\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(ValueError, "directly beneath"):
+                cleanup_report(report, temporary_directory=temporary_root)
+
+            self.assertTrue(report.exists())
+
+    def test_rejects_symlink(self):
+        """Reject a report symlink without deleting its target."""
+        with tempfile.TemporaryDirectory() as directory:
+            temporary_root = Path(directory)
+            target = temporary_root / "newton-1.5.0-rc-report.md"
+            target.write_text("keep\n", encoding="utf-8")
+            report = temporary_root / "newton-1.5.0-prerelease-report.md"
+            try:
+                report.symlink_to(target)
+            except OSError as error:
+                self.skipTest(f"symlinks are unavailable: {error}")
+
+            with self.assertRaisesRegex(ValueError, "symlink"):
+                cleanup_report(report, temporary_directory=temporary_root)
+
+            self.assertTrue(report.is_symlink())
+            self.assertEqual(target.read_text(encoding="utf-8"), "keep\n")
+
+
+if __name__ == "__main__":
+    unittest.main()

.claude/skills/release-audit/scripts/test_cleanup_report.py

@@ -1,103 +1,116 @@
 ---
 name: release-changelog
-description: Use when editing, auditing, or preparing Newton CHANGELOG.md for a release, especially to make upgrade-impact information actionable for developers.
+description: Use when auditing Newton changelog fragments, building a dated release changelog, or synchronizing a release build back to main.
 ---
 
 # Newton Release Changelog
 
-Maintain `CHANGELOG.md` as the detailed upgrade source of truth. Release notes
-and release announcements carry the high-level summary; the changelog should
-preserve specific breaking changes, removals, deprecations, behavior/default
-changes, dependency constraints, and migration guidance.
-
-## Workflow
-
-1. Protect released history first. Diff `CHANGELOG.md` from the latest stable
-   tag and inspect every hunk under a dated version header. Move late PR entries
-   accidentally added to a released section into the current `[Unreleased]`
-   section. Change released history only with explicit maintainer approval.
-2. Identify the release ref and comparison base. For final releases, use the
-   final tag or release branch. For RC prep, use the latest RC tag as temporary
-   ground truth and verify against the previous released tag.
-3. Read the current `CHANGELOG.md` section being edited, the release audit if
-   one exists, and PRs behind unclear entries. Do not rely only on commit
-   subjects for migration guidance.
-4. Check completeness from the previous GA or micro release through the release
-   ref, including RC fixes. Compare the range with the release audit and add
-   missed user-visible changes.
-5. Preserve information. Rephrase, split, merge, and regroup entries only when
-   the facts remain intact. Ask before deleting information, omitting a
-   questionable entry, or downgrading a user-visible change to silence.
-6. Use the existing Keep-a-Changelog categories (`Added`, `Changed`,
-   `Deprecated`, `Removed`, `Fixed`). Keep migration and retesting guidance in
-   the affected entries; release notes carry the summary.
-7. Within each category, group entries by the current release's user-facing
-   feature areas or migration themes when this improves readability.
-8. Remove exact and semantic duplicates within the release, not only identical
-   wording. If a feature and a fix for that feature both landed during the same
-   release cycle, consolidate the entries around the final user-visible
-   behavior instead of recording it once as `Added` and again as `Fixed`.
-9. Audit category boundaries before finalizing. Keep `Added` for new public
-   APIs, options, features, examples, and docs; move existing-API behavior
-   changes, new warnings, default changes, and importer/solver semantics into
+Pending user-facing changes live in Towncrier fragments under `changelog/`.
+`CHANGELOG.md` is generated only on a release branch. Shipped sections are
+immutable; the assembled section for the pending release remains a rolling
+document until tagging. Follow `changelog/README.md` as the command and format
+authority.
+
+## Audit pending changes
+
+1. Identify the release ref and comparison base. Audit `release-X.Y` once it
+   exists; otherwise audit the intended main ref.
+2. Protect released history. Diff `CHANGELOG.md` from the latest stable tag and
+   require explicit maintainer approval for edits to dated sections.
+3. Render a non-mutating preview, which also validates Towncrier's renderable
+   fragment filenames:
+   ```bash
+   uvx --from towncrier==25.8.0 towncrier build --draft \
+     --version X.Y.Z --date YYYY-MM-DD
+   ```
+4. Compare the preview with the release audit and commit range from the previous
+   release. Inspect `.skip` reasons separately.
+5. Preserve information. Rephrase, split, merge, or recategorize fragments only
+   when the facts remain intact. Ask before deleting information or downgrading
+   a user-visible change.
+6. Use only `Added`, `Changed`, `Deprecated`, `Removed`, and `Fixed`, in that
+   order. Keep migration and retesting guidance in affected entries.
+7. Remove exact and semantic duplicates. When a feature and its fix both land
+   in one cycle, describe the final user-visible behavior once.
+8. Keep `Added` for new public APIs, options, features, examples, and docs. Put
+   existing-API behavior, warning, default, importer, and solver changes in
    `Changed`, even when they expand support.
-10. Add same-repository PR references as compact `(#NNNN)` references
-   selectively, not mechanically. Prioritize high-importance entries:
-   breaking/default-changing behavior, public API additions that affect
-   migration, deprecations, removals, and major support fixes. Do not add PR
-   refs to every routine docs, example, cleanup, or minor fix entry.
-11. Before adding a PR reference, verify that the PR actually introduced the
-   change being cited. Prefer local history such as `git log --oneline` and
-   `git show --name-only <commit>`; skip ambiguous references rather than
-   guessing.
-12. For each breaking, removed, deprecated, or default-changing entry, include
-   migration guidance or a clear action: replacement symbol, opt-out flag,
-   compatibility setting, or what to re-test.
-13. Avoid directing users to private/internal APIs as migration targets. If a
-   public alias is deprecated because storage is becoming internal, say to avoid
-   depending on that data directly rather than pointing at underscore-prefixed
-   members.
-14. Separate internal cleanup from public API removals. If an internal symbol is
-   mentioned for completeness, label it as internal and do not imply users must
-   migrate unless it was public.
-15. Verify restored APIs against the final/RC tag before classifying removals.
-    For example, if a public symbol was removed during development but restored
-    before the release tag, do not list it as removed.
-16. When moving entries between release sections, make sure the information is
-    not duplicated under an older released version and the historical section
-    still reflects what actually shipped there.
-17. Perform a second editorial pass after regrouping. Re-read the source entries
-    and the final diff to catch user-relevant behavior, limitations, opt-in
-    conditions, changed defaults, compatibility details, or migration actions
-    lost during condensation.
-
-## Post-release reconciliation
-
-Merge a release branch's finalized changelog back to `main` through a dedicated
-feature branch and changelog-only PR:
-
-1. Fetch the canonical remote and create the feature branch from the latest
-   `upstream/main`, not from the release branch.
-2. Use the final tag as the source of truth.
-3. Keep `## [Unreleased]` first and preserve all post-cut entries not shipped
-   in the release. Do not replace the whole file with the release-branch copy.
-4. Insert the finalized release section immediately below `[Unreleased]` and
-   keep shipped entries only in that dated section. Resolve semantic overlap so
-   the same user-facing change is not recorded twice.
-5. Verify that only `CHANGELOG.md` changes, the dated section matches the final
-   tag, and older released sections remain unchanged.
+9. Give every breaking, removed, deprecated, or default-changing entry a
+   concrete action. Never direct users to `newton._src`.
+10. A numeric fragment identifier is a GitHub issue number. Towncrier renders
+    its issue link automatically; do not rewrite it as a pull request number.
 
-## Checks
+## Assemble the release during RC stabilization
+
+After the initial release scope has been audited on `release-X.Y`, assemble the
+current fragments early enough for maintainer review:
+
+```bash
+uvx --from towncrier==25.8.0 towncrier build --draft \
+  --version X.Y.Z --date YYYY-MM-DD
+uvx --from towncrier==25.8.0 towncrier build --yes \
+  --version X.Y.Z --date YYYY-MM-DD
+git rm --ignore-unmatch "changelog/*.skip"
+git add -A CHANGELOG.md changelog
+```
+
+Review and approve the draft before running the mutating command. Towncrier
+inserts the dated section below `[Unreleased]` and deletes rendered fragments.
+It ignores `.skip` files, so remove those explicitly. Review the staged diff in
+a changelog-only pull request labeled `release-management`.
+
+After assembly, apply the audit rules above to the dated section: verify
+completeness, grouping, deduplication, wording, categories, and migration
+guidance. Keep editorial cleanup in the changelog-management commits that will
+later be synchronized to `main`.
 
-Run targeted searches before finishing:
+The first Towncrier release requires one migration audit. The insertion marker
+sits above the legacy `[Unreleased]` entries so they remain under the first
+generated release title. Merge duplicate category headings without dropping or
+duplicating an entry. Later releases need no special handling.
+
+Treat the assembled section as a rolling document. For every later cherry-pick
+before tagging:
+
+1. Validate the new fragments and render them with `towncrier build --draft`.
+2. Fold the previewed entries into the existing dated section without creating
+   a second release heading.
+3. Delete exactly the consumed `.md` and `.skip` fragments, then stage
+   `CHANGELOG.md` and `changelog/`.
+4. Rerun the changelog cleanup and `release-audit` checks, and merge the update
+   as another changelog-only `release-management` pull request.
+
+Final GA preparation verifies the completed section and confirms that no
+release-branch fragments remain. Do not postpone the full cleanup until GA.
+
+## Synchronize to main
+
+After tagging:
+
+1. Create a changelog-only branch from current `main`.
+2. Cherry-pick, in order, every changelog-management commit from `release-X.Y`:
+   the initial Towncrier build, editorial cleanup, and all later cherry-pick
+   additions.
+3. Confirm fragments deleted by those commits disappear while fragments added to
+   `main` after the branch cut remain under `changelog/`.
+4. Confirm the dated section matches the release tag and older history is
+   unchanged.
+5. Open a changelog-only pull request labeled `release-management`.
+
+Do not replace the whole file with the release-branch copy. The commits'
+path-level deletions are what preserve main-only fragments.
+
+## Checks
 
 ```bash
-git diff v<latest-release> -- CHANGELOG.md
-git log --oneline <previous-release>..<release-ref>
-rg -n "removed|removal|deprecated|will be removed|in favor of|use .* instead|renam|replac|default|breaking" CHANGELOG.md
-git diff -- CHANGELOG.md
+uvx --from towncrier==25.8.0 towncrier build --draft \
+  --version X.Y.Z --date YYYY-MM-DD
+git diff v<latest-release> -- CHANGELOG.md changelog
+git diff --cached --name-status -- CHANGELOG.md changelog
+rg -ni "removed|deprecated|in favor of|use .* instead|renam|replac|default|breaking" \
+  CHANGELOG.md changelog
 ```
 
-Confirm that no new hunk lands in a released section, then check for missing or
-duplicate entries, accidental deletions, stale removal targets, and missing
-migration guidance or PR references.
+Confirm that `[Unreleased]` is empty after the first migration, no dated history
+changed, released entries appear exactly once, and post-cut main fragments
+survive synchronization.

.claude/skills/release-changelog/SKILL.md

@@ -23,8 +23,18 @@ what users should know. Do not reproduce the full changelog; link to it.
    - RCs: state that this is a release candidate and what needs validation.
      If drafting final-release text from an RC tag or release branch, do not
      mention the RC; use the RC only as the temporary source of truth.
-2. Read the matching `CHANGELOG.md` section from the release tag or release
-   branch. Do not rely on `main` unless the release is actually cut from `main`.
+2. Choose changelog source material from the authoritative release ref:
+   - After the Towncrier build or tagging, read the matching dated
+     `CHANGELOG.md` section from the release tag or release branch.
+   - Before the build, check out the release branch, validate its pending
+     fragments, and render a non-mutating preview:
+     ```bash
+     uvx --from towncrier==25.8.0 towncrier build --draft \
+       --version X.Y.Z --date YYYY-MM-DD
+     ```
+     Draft from the preview and legacy `[Unreleased]` entries during the first
+     Towncrier transition. Do not run a mutating build merely to draft notes.
+   Do not rely on `main` unless the release is actually cut from `main`.
 3. Determine the previous release tag:
    - Patch release `X.Y.Z`, `Z > 0`: use the highest earlier `vX.Y.<Z'>` tag.
    - Feature release `X.Y.0`: use the highest `vX.<Y-1>.*` tag. If `Y == 0`,