DOC: Prefer API compatibility, log unavoidable breaks in a migration guide

.agents/agents/implementation.md

@@ -1,6 +1,6 @@
 ---
 name: PhysioTwin4D Implementation Agent
-description: Implements features, bug fixes, or refactors in PhysioTwin4D. Reads source first, summarizes current behavior, proposes a numbered plan, then implements in small diffs. Calls out breaking changes.
+description: Implements features, bug fixes, or refactors in PhysioTwin4D. Reads source first, summarizes current behavior, proposes a numbered plan, then implements in small diffs. Calls out breaking changes and logs them in the migration guide.
 tools: Read, Edit, Write, Bash, Glob, Grep
 ---
 
@@ -24,7 +24,9 @@ searching manually.
 3. Propose a numbered implementation plan. For non-trivial changes, stop and confirm.
 4. Implement in the smallest reviewable diff possible.
 5. Update docstrings and type hints for every changed public method.
-6. Note any breaking changes explicitly.
+6. Note any breaking changes explicitly, and append an entry for each one to
+   `docs/developer/migration_next.md` using the template at the bottom of that
+   file.
 
 ## Code rules
 
@@ -61,7 +63,11 @@ searching manually.
 
 ## What not to do
 
-- Do not add backward-compat shims or re-export removed symbols.
+- Do not break a public API unless the change is generally beneficial to future
+  users; prefer compatibility.
+- Do not add deprecation shims or re-export removed symbols. Log the break in
+  `docs/developer/migration_next.md` and, when the change is substantial, ship
+  a script that automates the conversion.
 - Do not add error handling for impossible internal states.
 - Do not create new files when editing an existing one suffices.
 - Do not add features beyond what was requested.

.agents/skills/check-conventions/SKILL.md

@@ -62,6 +62,16 @@ context such as class inheritance), then flag every occurrence of:
       or return value means. Only genuine deviations from the conventions in
       `CLAUDE.md` may be documented.
 
+### Migration guide
+- [ ] A deprecation shim, removed-symbol re-export, or removed-symbol stub
+      kept solely for backward compatibility. Break the API instead, and ship
+      a conversion script when the break is substantial.
+- [ ] A public class, method, CLI flag, or signature that the diff renames,
+      removes, or changes, with no matching entry in
+      `docs/developer/migration_next.md`. The entry may record `None needed`
+      for the conversion script when the break is not substantial. Report the
+      missing entry against the changed line.
+
 ## Output
 
 Group findings by file. For each finding, print:

.agents/skills/commit/SKILL.md

@@ -20,13 +20,26 @@ Instructions:
      that should not be committed, display an error, stop processing, and abort
    - Do NOT add any untracked files to the commit.
 
-2. Draft a commit message following the project convention (match style of recent `git log --oneline -10`):
+2. Scan the diff for breaking changes to the public API — renamed or removed
+   classes, methods, or CLI flags, changed signatures or defaults, changed
+   output file layouts.
+   - If there are none, continue.
+   - If there are any, append one entry per break to
+     `docs/developer/migration_next.md` before committing, following the
+     template at the bottom of that file: what changed, why it benefits future
+     users, before/after code, and the script that automates the conversion
+     (or `None needed`). Remove the `_No breaking changes recorded since ..._`
+     placeholder line once the first entry is added.
+   - `migration_next.md` is tracked, so `git commit -a` picks it up.
+   - Do not resolve a break by adding a deprecation shim or a re-export.
+
+3. Draft a commit message following the project convention (match style of recent `git log --oneline -10`):
    - Subject line: `<TAG>: <imperative summary>` (≤72 chars), where TAG is one of:
      `ENH` (new feature / enhancement), `FIX` (bug fix), `REF` (refactor),
      `TST` (tests only), `DOC` (docs/comments only), `MNT` (maintenance / config).
    - Optional body: 1–3 sentences explaining *why*, not *what*.
 
-3. Attempt the commit. Include a body only when it adds meaningful context:
+4. Attempt the commit. Include a body only when it adds meaningful context:
    ```bash
    git commit -a -m "<subject>" -m "<body>"
    ```
@@ -35,16 +48,16 @@ Instructions:
    git commit -a -m "<subject>"
    ```
 
-4. If the commit fails because a pre-commit hook rejected it:
+5. If the commit fails because a pre-commit hook rejected it:
    a. Read the hook output carefully.
    b. Fix every reported issue (formatting, lint errors, type errors, test failures, etc.).
       - For `ruff` formatting/lint: use `git diff --diff-filter=d --name-only HEAD -- '*.py'`
         to list modified, non-deleted `.py` files, then pass only those to
         `ruff check --fix` and `ruff format`. Do not run ruff project-wide.
       - For `mypy` errors: fix the type annotations in the flagged files.
       - For other hook failures: diagnose and fix the root cause; do NOT use `--no-verify`.
-   c. Return to step 3 and retry — repeat until the commit succeeds or you have exhausted reasonable fixes.
+   c. Return to step 4 and retry — repeat until the commit succeeds or you have exhausted reasonable fixes.
    d. If an issue cannot be fixed automatically (e.g. a failing test unrelated to the current changes), report it to the user and stop.
 
-5. After a successful commit, print the one-line commit summary (`git log --oneline -1`)
+6. After a successful commit, print the one-line commit summary (`git log --oneline -1`)
    and remind the user: "Remember to `git push` when you are ready to publish this commit."

.agents/skills/impl/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Read relevant PhysioTwin4D source files, summarize current behavior, propose a brief plan, then implement the requested feature or refactor in small diffs. Calls out breaking changes.
+description: Read relevant PhysioTwin4D source files, summarize current behavior, propose a brief plan, then implement the requested feature or refactor in small diffs. Calls out breaking changes and logs them in the migration guide.
 ---
 
 Implement the following in the PhysioTwin4D repository:
@@ -13,5 +13,11 @@ Instructions:
 4. Implement in the smallest reviewable diff possible.
 5. Update docstrings and type hints for every changed public method.
 6. Run `ruff check . --fix && ruff format .` after editing Python files.
-7. Explicitly note any breaking changes introduced.
-8. Do not add features beyond what was requested.
+7. Prefer compatibility. Break a public API only when the change is generally
+   beneficial to future users, and never via a deprecation shim, removed-symbol
+   re-export, or removed-symbol stub — provide a conversion script when the
+   change is substantial.
+8. Explicitly note any breaking changes introduced, and append an entry for
+   each to `docs/developer/migration_next.md` using the template at the bottom
+   of that file.
+9. Do not add features beyond what was requested.

.cursor/rules/project-standards.mdc2

@@ -44,14 +44,25 @@ git mv old_name.py new_name.py
 - Update existing README.md files when needed
 - API documentation in existing docs structure
 
-## Backward Compatibility
+## Compatibility and Migration
 
-**Backward compatibility is NOT a priority** for this project:
+**Prefer compatibility.** Break a public API only when the change is generally
+beneficial to future users:
 
-- Feel free to make breaking changes to improve code quality
-- Remove deprecated code without extensive migration paths
-- Update APIs for clarity and consistency
-- Prioritize modern, clean design over legacy support
+- Do not add deprecation shims, removed-symbol re-exports, or removed-symbol
+  stubs
+- When a break is substantial, ship code that automates the conversion instead
+- Every commit that breaks a public API adds an entry to
+  `docs/developer/migration_next.md` in that same commit — what changed, why it
+  benefits future users, before/after code, and the conversion script (or
+  `None needed` when the break is not substantial)
+- At release, archive the guide under the new version and start a fresh one:
+
+```bash
+VERSION=$(bumpver show --no-fetch | sed -n "s/^Current Version: //p")
+git mv docs/developer/migration_next.md "docs/developer/migration_$VERSION.md"
+# Retitle the archived file, then recreate migration_next.md from its template
+```
 
 ## Code Style
 

AGENTS.md

@@ -8,8 +8,9 @@ medical image of a subject, extracting anatomic models, and then using AI
 surrogates to estimate the subject's physiological processes (initially
 cardiac and respiratory motion, expanding to electrophysiology, blood flow,
 and organ perfusion). It is an **early-alpha** scientific Python library.
-Clarity beats premature optimization. Breaking changes are acceptable.
-Backward compatibility is not a goal.
+Clarity beats premature optimization. Prefer compatibility: break a public API
+only when the change is generally beneficial to future users, and record every
+break in the migration guide (see below).
 
 ## Role
 
@@ -98,6 +99,30 @@ python -m pytest tests/ --create-baselines
 
 Version bumping: `bumpver update --patch`, `--minor`, or `--major`.
 
+## Migration Guide
+
+PhysioTwin4D prefers compatibility. Break a public API only when the change is
+generally beneficial to future users. Never add deprecation shims,
+removed-symbol re-exports, or removed-symbol stubs; when a break is
+substantial, ship code that automates the conversion instead.
+
+At commit time: if the diff breaks a public API, append an entry to
+`docs/developer/migration_next.md` in that same commit — what changed, why it
+benefits future users, before/after code, and the conversion script (or
+`None needed`). Follow the entry template at the bottom of that file.
+
+At release time:
+
+```bash
+bumpver update --patch
+git mv docs/developer/migration_next.md docs/developer/migration_<new_version>.md
+# retitle the archived file to "Migration Guide - <new_version>"
+# recreate docs/developer/migration_next.md from its entry template
+```
+
+The `Developer Guides` toctree in `docs/index.rst` globs
+`developer/migration_*`, so archived guides need no further wiring.
+
 ## graphify
 
 This project keeps a knowledge graph at `graphify-out/` covering god nodes,
@@ -191,7 +216,9 @@ graphify update .               # refresh after code changes (AST-only, no API c
   changes.
 - Keep diffs small and reviewable.
 - Prefer editing existing modules over creating new ones.
-- No backward-compatibility shims: just change the code.
+- No deprecation shims, removed-symbol re-exports, or removed-symbol stubs.
+  Change the code, log the break in `docs/developer/migration_next.md`, and
+  provide a conversion script when the change is substantial.
 
 ## Testing Role
 

CLAUDE.md

@@ -71,7 +71,17 @@ Strong success criteria let you loop independently. Weak criteria
 
 ## 5. Project-Specific Rules
 
-- Breaking changes are acceptable. Backward-compatibility shims are not.
+- Prefer compatibility. Break a public API only when the change is generally
+  beneficial to future users.
+- Never add deprecation shims, removed-symbol re-exports, or removed-symbol
+  stubs. When a break is substantial, ship code that automates the conversion
+  instead.
+- Every commit that breaks a public API must add an entry to
+  `docs/developer/migration_next.md`: what changed, why it benefits future
+  users, before/after code, and the conversion script (or `None needed`).
+- At release time, `git mv docs/developer/migration_next.md
+  docs/developer/migration_<version>.md`, retitle it, and start a fresh
+  `migration_next.md` from its entry template.
 
 ---
 
@@ -174,12 +184,16 @@ Use `git mv` / `git rm` — not `mv` / `rm` — to preserve history.
 Do **not** create new `.md` files unless explicitly requested.
 Document via docstrings and inline comments.
 
+Exception: the migration guide. Append to `docs/developer/migration_next.md`
+whenever a commit breaks a public API, and create
+`docs/developer/migration_<version>.md` plus a fresh `migration_next.md` at
+release time.
+
 ## Code Style
 
 - Double quotes for strings and docstrings
 - Full type hints (`mypy` strict; `disallow_untyped_defs = true`)
 - `Optional[X]` not `X | None` (ruff `UP007` suppressed)
-- Breaking changes are acceptable — backward compatibility is not a priority
 - Max line length: 88 characters
 - Follow behavior guidelines.
 

docs/contributing.rst

@@ -231,6 +231,10 @@ Pull Request Guidelines
 * **Pass all tests**: CI must pass
 * **Update documentation**: Document new features
 * **Add release note**: Document user-facing changes in the pull request
+* **Log breaking changes**: If the change breaks a public API, add an entry to
+  ``docs/developer/migration_next.md`` in the same commit, covering what
+  changed, why it benefits future users, before/after code, and the script that
+  automates the conversion. Do not add deprecation shims instead.
 
 Testing
 =======
@@ -375,7 +379,9 @@ Review Criteria
 * **Tests**: Are there adequate tests?
 * **Documentation**: Is it properly documented?
 * **Performance**: Are there any performance concerns?
-* **Compatibility**: Does it maintain backwards compatibility?
+* **Compatibility**: Does it avoid needless breaking changes, and is every
+  unavoidable break recorded in ``docs/developer/migration_next.md`` with a
+  conversion path rather than a deprecation shim?
 
 Reporting Issues
 ================
@@ -427,12 +433,22 @@ Maintainers only:
    # Bump version
    bumpver update --patch
 
+   # Archive the migration guide under the new version, then start a fresh one
+   VERSION=$(bumpver show --no-fetch | sed -n "s/^Current Version: //p")
+   git mv docs/developer/migration_next.md "docs/developer/migration_$VERSION.md"
+   # Retitle the archived file to "Migration Guide - $VERSION"
+   # Recreate docs/developer/migration_next.md from its entry template
+
    # Build package
    python -m build
 
    # Upload to PyPI
    python -m twine upload dist/*
 
+The ``Developer Guides`` toctree in ``docs/index.rst`` globs
+``developer/migration_*``, so archived guides appear in the sidebar without
+further edits.
+
 Community Guidelines
 ====================
 

docs/developer/ai_assistants.rst

@@ -13,6 +13,12 @@ assistant; ``CLAUDE.md`` adds Claude-specific instructions. Role subagents live
 in ``.agents/agents/`` and slash-command skills in ``.agents/skills/``. Read
 those before hand-writing a prompt that repeats project conventions.
 
+One of those conventions binds every assistant: PhysioTwin4D prefers
+compatibility, breaks a public API only when the change is generally beneficial
+to future users, and never ships deprecation shims. Any commit that does break
+an API must add an entry to :doc:`migration_next` describing the change and the
+code that automates the conversion.
+
 graphify
 ========
 
@@ -49,4 +55,5 @@ See Also
 
 * :doc:`core`
 * :doc:`extending`
+* :doc:`migration_next`
 * :doc:`../contributing`

docs/developer/architecture.rst

@@ -66,3 +66,9 @@ VTK-to-USD boundary.
 
 The installed CLI commands are thin wrappers around these workflow classes.
 They are the best executable references for supported API usage.
+
+See Also
+========
+
+* :doc:`extending`
+* :doc:`migration_next`

docs/developer/extending.rst

@@ -84,3 +84,4 @@ See Also
 * :doc:`architecture`
 * :doc:`workflows`
 * :doc:`utilities`
+* :doc:`migration_next`

docs/developer/migration_next.md

@@ -0,0 +1,41 @@
+# Migration Guide — Unreleased
+
+Breaking changes committed since the last release, and how to update code that
+depends on them.
+
+PhysioTwin4D prefers compatibility: public APIs are broken only when the change
+is generally beneficial to future users. When a break is unavoidable, the
+project does **not** ship deprecation shims or removed-symbol stubs. Instead,
+substantial changes ship with code that automates the conversion, and every
+break is recorded here in the commit that introduces it.
+
+At release time this file is renamed `migration_<version>.md` and a fresh
+`migration_next.md` is started for the next cycle.
+
+_No breaking changes recorded since 2026.08.0._
+
+## Entry template
+
+Append one section per breaking change, newest last, using this shape:
+
+````markdown
+## <symbol, module, or CLI flag> — <one-line summary>
+
+**Change:** what moved, was renamed, or changed signature.
+
+**Why:** the benefit to future users that justified the break.
+
+**Before**
+
+```python
+old_call(argument)
+```
+
+**After**
+
+```python
+new_call(argument, required_option="value")
+```
+
+**Automated conversion:** `<path to script or CLI>`, or `None needed`.
+````

docs/index.rst

@@ -211,6 +211,7 @@ close every section.
    :maxdepth: 2
    :caption: Developer Guides
    :hidden:
+   :glob:
 
    developer/architecture
    developer/extending
@@ -223,6 +224,7 @@ close every section.
    developer/usd_generation
    developer/utilities
    developer/ai_assistants
+   developer/migration_*
 
 .. toctree::
    :maxdepth: 1

utils/ai_agent_github_reviews.py

@@ -646,7 +646,10 @@ def build_prompt(
 
         Rejection triggers (from {guidance_names} — treat these as hard rules):
         - Introduces `X | None` instead of `Optional[X]` (ruff UP007 is suppressed)
-        - Adds backward-compat shims, re-exports, or removed-symbol stubs
+        - Adds a deprecation shim, removed-symbol re-export, or removed-symbol
+          stub instead of a `docs/developer/migration_next.md` entry (that entry
+          needs a conversion script only when the break is substantial; it may
+          record `None needed` otherwise)
         - Adds error handling for internal states that cannot happen
         - In classes that inherit from `PhysioTwin4DBase`, uses `print()` instead
           of `self.log_info()` / `self.log_debug()`