[guijacquemet]

Implements MorphoBricks-Spec amendment RH1 (Spec PR #37, commit 2cbebf8; owner decision of 2026-11-13, MorphoFeature #220 audit gap 1).

Why

Real scanner files store interleaved RGB under a header that does not say RGB. The Zenodo 4550300 brightfield cores are TIFF, photometric MINISBLACK, 3 samples per pixel, contiguous. A unit declared image_type = "rgb" was refused with R_IMAGE_TYPE_CONTRADICTS_HEADER, so such data could not be analysed without rewriting its pixels.

What changes

• Description key rgb_header_override (boolean, on a technical-repeat unit):
  • a non-boolean value is E_TYPE (phase 3);
  • the key on a unit without image_type = "rgb" is the new E_RGB_OVERRIDE_WITHOUT_RGB (phase 5);
  • the canonical writer keeps it;
  • the notebook draft keeps it on re-save, and switching a unit to separate channels drops it.
• Physical check (physical_check.py): for a unit declared rgb with the key, a header that says "not RGB" is accepted only when the image has exactly three interleaved samples (header only; pixels never examined). Samples 0, 1, 2 become R, G, B.
  • An image without three interleaved samples is the new R_RGB_OVERRIDE_NOT_THREE_SAMPLES. It is reported first for that unit, so a mixed unit gives this code rather than R_UNIT_NOT_HOMOGENEOUS.
  • A unit with the key whose header already says RGB is accepted as header-verified.
  • Without the key, the contradiction is still R_IMAGE_TYPE_CONTRADICTS_HEADER, and for three interleaved samples the message says to declare rgb_header_override = true.
  • OME-Zarr is unchanged.
• Header reading: the new io module tiff_colour.py reads rgb_samples, photometric and interleaved_samples; _rgb_samples moved there from metadata.py. TiffMetadata gains photometric and interleaved_samples.
• Manifest: an overridden unit's record gains image_type_header_overridden: true and header_photometric (e.g. "minisblack"; several values sorted and joined), and image_type_header_verified is false for it. Every other unit's record keeps exactly its keys.
• Reconciliation: ObservedUnit.three_samples keeps an accepted override from counting as a changed unit. Adding or removing the key reopens no repeat confirmation, because it changes no channel ID.
• Test fixtures: testing_described writes overridden units as MINISBLACK 3-sample images.
• Docs: AGENTS.md, CHANGELOG, docs/contract.md, docs/user_guide.md.

Not changed / deliberate

• Spec pin not moved: Differing channel names across images are only a warning (channels pooled by index) #37 is unmerged. Fixtures v40/i140/i141 are rebuilt inline in tests/test_rgb_header_override.py: v40 and i141 are the vendored v28 plus exactly the Spec's added lines, and i140 is copied.
  • test_spec_rules_table.py now allows exactly the new field and code ahead of the pin. That allowance fails once the pin contains them, which forces removing it at the re-pin.
• Notebook: no control for the key in this PR; the key is kept on re-save.

Tests and checks

• New tests: tests/test_rgb_header_override.py (23) cover P36 (a)–(d) on real tifffile-written files, plus E_TYPE, E_RGB_OVERRIDE_WITHOUT_RGB, the message naming the key, the manifest keys, and channels R, G, B in stored order through RunInputs.
• Full check: python tools/check.py: Ruff and format pass, code rules pass (one baseline entry lowered, 649 → 646), 5516 passed, 4 skipped. The 4 skips are the same environment skips as on unmodified main (5493 passed, 4 skipped).
• Manual check on a real Zenodo 4550300 file (1B_A3_BF.tif, not committed):
  • without the key: refused, and the message names the key;
  • with the key: the run is written, RunInputs gives channels ('R','G','B'), and read_plane equals stored samples 0, 1, 2 at (3, 2048, 2048).

Merge after Spec #37. The bricks re-pin the Spec and preprocessing in the next pin wave. The owner reviews before merge.

---

Generated by Claude Code