ENH: Add migration sentinel maintenance tooling and documentation

Add MigrationSentinels.py with three subcommands: validate, which CI runs so
a malformed sentinel cannot merge; expire-itk, which removes every sentinel
at a tag because all of them ship in it; and expire-downstream, which reduces
a consumer's two-arm condition to its version arm once the tag exists.

validate also rejects a misspelled prefix. Such a file is invisible to the
ITK_MIGRATION_*.md glob, so the sentinel would silently never be published.

expire-downstream pins UTF-8 on the files it rewrites. The locale default is
cp1252 on Windows, and the rewrite is in place and not atomic, so an
unpinned encoding can silently corrupt non-ASCII content.

Author: hjmjohnson

.github/workflows/migration-sentinels.yml

@@ -0,0 +1,28 @@
+name: Migration sentinels
+
+# A malformed sentinel is silently ignored by the CMake glob, so it would never
+# be published to downstream projects. Validate on every PR that touches one.
+
+on:
+  pull_request:
+    paths:
+      - 'CMake/MigrationSentinels/**'
+      - 'Utilities/Maintenance/MigrationSentinels.py'
+      - '.github/workflows/migration-sentinels.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Validate migration sentinels
+        run: |
+          python3 Utilities/Maintenance/MigrationSentinels.py validate \
+            || {
+              echo "::error::A migration sentinel is malformed. See" \
+                   "Documentation/docs/contributing/migration_sentinels.md"
+              exit 1
+            }

Documentation/docs/contributing/index.md

@@ -468,6 +468,7 @@ ITK Git Cheatsheet <https://github.com/InsightSoftwareConsortium/ITK/blob/main/D
 CDash Dashboard <https://open.cdash.org/index.php?project=Insight>
 dashboard.md
 updating_third_party.md
+migration_sentinels.md
 python_packaging.md
 ../README.md
 ```

Documentation/docs/contributing/migration_sentinels.md

@@ -0,0 +1,85 @@
+# Migration sentinels
+
+A migration sentinel lets a downstream project detect, at CMake configure time,
+that one specific ITK change is present — during the interval between ITK tags,
+which can run two years.
+
+The motivating case is `git bisect`. A downstream project bisecting ITK to find
+which change broke it is configured against a sequence of arbitrary commits, and
+at each step must choose which baseline images to test against. Sentinels are
+plain files in the source tree, so they are readable in a detached `HEAD`, a
+shallow clone, or an exported archive — states in which `git describe` fails and
+`git rev-list --count` silently returns a wrong answer.
+
+Sentinels are **not** a general feature-detection API. They are removed at each
+tag. Sentinels are intended **only** for fine-grained configure-time decisions
+between tagged releases.
+
+## Adding a sentinel
+
+Add one file to `CMake/MigrationSentinels/` containing a single line of
+description:
+
+```
+CMake/MigrationSentinels/ITK_MIGRATION_PR6532.md
+```
+
+```markdown
+itk::Math::SVD replaces vnl_svd for ITK-internal consumers; see PR #6532.
+```
+
+Choose exactly one naming pattern:
+
+| Pattern | When |
+|---|---|
+| `ITK_MIGRATION_PR<N>` | **Strongly preferred** — traceable to the pull request. |
+| `ITK_MIGRATION_<DESCRIPTIVE_NAME>` | No single PR captures the change. |
+| `ITK_MIGRATION_HASH_<githash>` | Only a commit identifies the change. |
+
+CI rejects a name matching none of these. It also rejects a misspelled prefix,
+which would otherwise be silently ignored by the glob and never published.
+
+## Using a sentinel downstream
+
+```cmake
+find_package(ITK REQUIRED)
+
+if(ITK_VERSION VERSION_GREATER_EQUAL 6.1.0
+   OR ITK_MIGRATION_PR6532 IN_LIST ITK_MIGRATION_SENTINELS)
+  set(BASELINE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Baseline/post-6532)
+else()
+  set(BASELINE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Baseline/legacy)
+endif()
+```
+
+Name the ITK release you expect to contain the change as the version arm. Both
+arms are required:
+
+- The **sentinel arm** is true between tags, before any release contains it.
+- The **version arm** is true after the tag, once sentinels have been expired.
+
+Against an ITK predating this mechanism, `ITK_MIGRATION_SENTINELS` is unset,
+`IN_LIST` is false, and the legacy branch is taken — no guard needed. This is
+also why the mechanism is a list variable rather than a function: calling a
+function that older ITK does not define is a hard `Unknown CMake command`
+error, and CMake's `if()` cannot invoke a function anyway.
+
+## Expiring at a tag
+
+Run once after tagging:
+
+```bash
+python3 Utilities/Maintenance/MigrationSentinels.py expire-itk
+python3 Utilities/Maintenance/MigrationSentinels.py \
+  expire-downstream --tag 6.1.0 --repo ../BRAINSTools
+```
+
+Order does not matter and neither step is urgent. A downstream not yet rewritten
+keeps working against the tagged ITK because the version arm is now true.
+
+## Why this is not in a compiled header
+
+`ITK_MIGRATION_SENTINELS` is exported through `ITKConfig.cmake` only. Embedding
+it in `itkConfigure.h` would change every translation unit's preprocessed output
+on most merges and destroy ccache hit rates on every build machine. The
+`MigrationSentinelConfigureHeaderGuard` test enforces this.