[guijacquemet]

PP-13 of the v0.4.0 plan (design v0.4 §8, §9; plan §10 release checklist). Based on main af8f769. Docs only, plus the version bump: no behaviour change.

What's in it

• docs/migration-0.3-to-0.4.md (new; linked from the README and user guide §7). Every breaking change from v0.3.4, each with what changed, why (the science rule) and what to do.
  • For users: manifest v1→v2 (rerun; no reusable rows); the axis check and per-file plain-stack confirmation; modes, recorded inputs and the lock; the report; calibration.csv/calibrate; the design command and the stricter readers; masks (image_named_as_mask error, the masks field, stated/shared masks, mask_layout, labels always used); OME-Zarr (NGFF 0.1/0.2 and stores without axes refused, declared-role matching, rc3 fingerprints count as changed); convert replacing convert_tiffs (record v2, copy hashes); link containment, --log rules and exit codes; staging, resume and crash-consistent publication.
  • For bricks: RunInputs (open, fovs, pixel_sizes, read_plane/read_image, read_mask, design, the full list of refusals including unrecorded files, the conversion record and copy hashes, and the zarr extra); a removed-API table (convert_tiffs/zarr_export, the normalization shims, check_declared_axes/declared_axes_transposed, find_masks(ome_zarr_labels=), PYRAMID_OPTIONS, force_rebuild/--force-rebuild, PhysicalSizes pickles); cache keys.
• CHANGELOG.md (new; the repo had none): 0.4.0, grouped into breaking, added, fixed and removed, with PR and issue numbers (Keep an unreadable experiment_design.csv untouched in step 1 #61–Micrometre conversions are always positive and finite; check and design exit 1 on errors (#93) #133; issues [Audit/Correctness] same_objects counts many-to-one IoU overlaps as one-to-one matches #67, [Audit/Scientific integrity] OME-Zarr with matching axis letters can be processed under contradictory confirmed roles #72–[Sad Catapella B3][Memory] Blockwise pyramid region selector does not enforce a viable minimum budget #76, [Sad Catapella B3][Performance] TIFF-to-Zarr conversion rereads the converted pixels to compute histograms #79–[Sad Catapella B4][Scientific identity] Lenient experiment-design reader silently selects last duplicate column #83, [Sad Catapella B5][Scientific integrity] Aggregate OME-Zarr fingerprint misses changed chunks when newest mtime is unchanged #86–[Sad Catapella B5][Correctness] Channel-label copy freshness check accepts missing or truncated OMERO metadata #88, [Sad Catapella B5][Scientific integrity] Source files may change between fingerprint capture and histogram publication #90, [Sad Catapella B6][Scientific calibration] Reused OME-Zarr copies are not checked for numeric pixel-scale correctness #92–[Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94, [Sad Catapella B6][Performance] TIFF-to-Zarr conversion reopens headers to read physical calibration already inspected #96, [Sad Catapella B8][Scientific identity] Changing notebook output directory retains and can overwrite the wrong confirmed experiment design #98, [Sad Catapella B8][Data safety] CLI --log opens arbitrary files before validating experiment and output paths #99).
• docs/colab-release-check.md (new): the hand-check lists of PP-8d: Colab and LabConstrictor readiness of the notebook #118, PP-10d: the notebook's masks-step button (Describe the masks) #123 and PP-11b: the notebook's Make named-axis copies card #127 in one list (23 items). Two items were updated for later changes: the stale-lock button (PP-10a) and .publish/.staging (PP-12). It says plainly that the notebook is verified headless only until the major release. The release checklist and the README point to it.
• Docs pass:
  • README: the stale masks bullet (it said 2-D masks of stacks are always refused; it now covers the shared YX statement); new RunInputs and resume bullets; the upgrade note.
  • User guide §7: upgrading from v0.3 or rc3.
  • Contract: §9.3 is moved back before §9.4; the obsolete "Former text" of the removed declared-axes row is dropped; "breaking for the next release" becomes "breaking in v0.4.0".
  • Notebook step 3: a note on resuming after an interruption.
• Plan §10:
  • PP-13 is marked done.
  • The release checklist is completed: CHANGELOG and migration entries, the full gate, and a Colab check for the major release only (after the data-flow audit and the matrix run).
  • The coordinator follow-ups are recorded: the pair_counts exact-half tie break; masks not fingerprint-bound during a run; a .tmp left after a kill; to_micrometers refusing numpy scalars other than float64; the axis card not showing the recomputed size warnings.
• Version 0.4.0rc4: set in pyproject.toml, RELEASE_TAG, current_version, notebook_latest_versions.yaml and the Step 0 Colab callout. The owner tags it. The final 0.4.0 bump comes after the audit.

Bugs found (not fixed here)

• length_units.to_micrometers(np.float32(0.5), "micrometer") and np.int64(2) raise ValueError: … is not a number; Python int/float and np.float64 are accepted. This was confirmed in the venv and is recorded as follow-up (d).
• The other four follow-ups are recorded as given; I did not re-verify them.

Owner questions

1. PhysicalSizes pickles. The design change log says breaking old pickles is accepted. In practice, a v0.3.4-shaped instance (without the new invalid field) pickles and loads fine, with invalid=None, because the dataclass default is a class attribute. The guide therefore says "not supported / not guaranteed" rather than "broken". Is that wording right?
2. Plan question 66 is still marked "pending the owner's confirmation" (the header overflow is a warning, and design exits 1 after a write that leaves a conflict). The CHANGELOG and the guide describe it as implemented.

Gate (own worktree and uv venv, Python 3.11, .[dev,notebook,zarr], at 744b345)

• ruff check and ruff format --check: clean (204 files).
• tools/check.py --rules: exit 0.
• pytest: 1997 passed, 2 skipped, 1 warning.
  • The skips are the expected ones: test_discovery.py:665 (root) and test_cli_log.py:165 (case-insensitive FS check).
  • The warning is the existing tifffile "closed file" warning.

---

Generated by Claude Code

[guijacquemet]

Independent review, merged with a merge commit.

Verified:

• The diff af8f769..744b345 is docs plus the version bump only. No src/ or tests/ change.
• 0.4.0rc4 is consistent in pyproject, notebook RELEASE_TAG and current_version, the Colab callout, and notebook_latest_versions.yaml.
• About 45 claims in the migration guide and CHANGELOG were checked against the code. All refusal codes, the RunInputs methods, the conversion record v2, the NGFF 0.1/0.2 rule, the CLI flags, the exit codes and the staging/publication names exist as stated. Every removed API is gone.
• Every relative link and anchor in README, user guide, migration guide, CHANGELOG and colab-release-check.md resolves.
• The plan §10 checklist references colab-release-check.md and limits the Colab check to the major release, after the data-flow audit and the matrix run.
• Plan question 66 stays marked pending the owner's confirmation.
• Gate: ruff check and format clean; pytest 1997 passed, 2 skipped (test_discovery.py:665, test_cli_log.py:165), 1 warning; tools/check.py --rules exit 0. CI is green on all 7 jobs.

No findings and no fixes were needed.

---

Generated by Claude Code