fix(mri): warn on all-False mask; document 6-connectivity erosion caveat

Addresses I1, I2, M1 from code review:
- Docstring step-2 now calls out 6-connectivity, iterations=1, and the
thin-feature erosion caveat (suggesting 26-connectivity for production).
- New paragraph documents the all-False WARNING behaviour.
- logger.warning emitted when cleaned.any() is False, reporting volume
min/max and effective threshold so silent feature-zeroing is visible
in production logs.
- .astype(bool) moved onto the binary_opening line; return is just cleaned.
- New regression test: constant-valued volume produces empty mask + WARNING.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/pipelines/mri_pipeline.py

@@ -63,8 +63,15 @@ def mask_brain(
          `None`, use the volume's mean as a robust auto-threshold (works on
          the synthetic fixture where brain ≫ background; for real data the
          caller should pass an Otsu or BET-derived threshold explicitly).
-      2. Morphological opening (`scipy.ndimage.binary_opening`) to remove
-         isolated noise voxels and disconnected fragments.
+      2. Morphological opening (`scipy.ndimage.binary_opening`, 6-connectivity,
+         iterations=1) to remove isolated noise voxels and disconnected
+         fragments. Note: thin features (< 3 voxels wide along any axis pair)
+         may be eroded entirely; for production data with cortical sheets or
+         sulcal bridges, prefer 26-connectivity or pass `iterations=0` upstream.
+
+    If the resulting mask is all-False (e.g. caller passed a threshold above
+    the volume's max intensity, or the volume is constant-valued), a WARNING
+    is emitted so silent feature-zeroing is visible in production logs.
 
     Args:
         volume: 3-D numeric `np.ndarray` (must satisfy `is_valid_volume`).
@@ -77,5 +84,12 @@ def mask_brain(
         intensity_threshold = float(volume.mean())
 
     raw = volume > intensity_threshold
-    cleaned = scipy_ndimage.binary_opening(raw, iterations=1)
-    return cleaned.astype(bool)
+    cleaned = scipy_ndimage.binary_opening(raw, iterations=1).astype(bool)
+    if not cleaned.any():
+        logger.warning(
+            "mask_brain produced an all-False mask "
+            "(volume min=%.4f, max=%.4f, threshold=%.4f); "
+            "downstream features for this volume will be all-zero.",
+            float(volume.min()), float(volume.max()), intensity_threshold,
+        )
+    return cleaned

tests/pipelines/test_mri_pipeline.py

@@ -103,3 +103,28 @@ class TestMaskBrain:
         # Without cleanup, the single voxel would survive. With morphological
         # opening, it must be removed.
         assert mask.sum() == 0
+
+    def test_constant_volume_returns_all_false_mask_with_warning(self) -> None:
+        """A constant-valued volume produces an empty mask AND logs a WARNING."""
+        import io
+        import logging
+
+        from src.core.logger import get_logger
+        from src.pipelines import mri_pipeline as mod
+
+        vol = np.full((8, 8, 8), 5.0, dtype=np.float64)
+
+        logger = get_logger(mod.__name__, level=logging.INFO)
+        handler = logger.handlers[0]
+        buf = io.StringIO()
+        original_stream = handler.stream
+        handler.stream = buf
+        try:
+            mask = mask_brain(vol)
+        finally:
+            handler.stream = original_stream
+
+        assert mask.sum() == 0
+        log_output = buf.getvalue()
+        assert "all-False mask" in log_output
+        assert "downstream features for this volume will be all-zero" in log_output