[guijacquemet]

Summary

Owner decision of 31 October 2026 (plan §12 question 43, follow-up to PR #61). This is a breaking API change for the next release.

• design.py: when the saved experiment_design.csv cannot be read, load_design(output_folder, repeats) now raises DesignCheckError. Before, it returned the default design together with a problem string. The error holds one issue, unreadable_experiment_design. Its message is read_confirmed_design's "The experiment design cannot be read: …" followed by the lenient reader's refusal, which names the line and column (for example experiment_design.csv, line 2, column confirmed_on: '26/10/2026' is not a date in the form YYYY-MM-DD …). The issue also gives the path and a suggested action, and the DesignFormatError is its __cause__. No default design is returned and the file is not touched. The return value is now (design, changes). The issue builder is shared with read_confirmed_design (_unreadable), so both readers give the same refusal text.
• notebook_ui.py (_open_design): catches the error and keeps the PR Keep an unreadable experiment_design.csv untouched in step 1 #61 behaviour: the file is left untouched, the refusal is shown in the red box, the questions start unanswered, and an explicit answer replaces the file.
• cli.py (check): prints the refusal and its suggested action and writes nothing. The exit code is unchanged. run never called load_design: it uses read_experiment_design and already refused such a file without writing it.
• Docs: contract §12 (Reading and Notebook rows) and §16 (Experiment design row, with the breaking-change note), user guide §5 (check), §8 (message code) and §9 (Python example), and plan §12 question 43.

Decisions

• Error type. I reused the existing DesignCheckError with the existing code unreadable_experiment_design, so the error carries a ValidationIssue (code, message, paths, action) like the rest of the brick. It is still a ValueError. DesignFormatError stays the lenient reader's own error and is chained as __cause__.
• Missing file. I kept the existing behaviour: load_design returns the default design and DesignChanges(). A missing file is the normal first run, not an unreadable file. A path that exists but cannot be read (for example a folder named experiment_design.csv, or an I/O error) does raise.
• Third return value. I dropped the third value (problem) rather than keeping it as an always-None field. Old callers that unpack three values now fail loudly instead of silently ignoring a field that no longer means anything.

Uses in other bricks (read-only grep of the local checkouts, not edited)

There are no uses of load_design or its problem value in CellPatcher (32b8f8a), MorphoCoverage (beadc9d), MorphoEmbed (f0092aa), MorphoFeature (60a7832), MorphoObjects (b5cafef), MorphoRelate (5ccbaac), fiberfeatures (e2f5b97) or morphobricks-normalization (f784c95). Those bricks read the design with read_confirmed_design, or with their own readers. The SHAs are the local checkout HEADs, which may be behind their remotes.

Notes for review

• The notebook was tested headless only (the existing PR Keep an unreadable experiment_design.csv untouched in step 1 #61 tests, unchanged, still pass). I did not look at it in a real JupyterLab.
• No version bump and no tag.

Tests

• New regression tests in tests/test_design.py:
  • load_design raises for a re-saved date, an NA repeat group, and a file without the columns (parametrised), and for a folder in place of the file. Each case checks the code, the message with its line and column, the path, the action and the cause, and that the file is unchanged.
  • A missing file gives the default design.
  • A saved design is read and reconciled.
  • check refuses an unreadable design without writing it.
• On old main (febe0a8), all 7 new tests fail: the unreadable cases with "DID NOT RAISE DesignCheckError", the two return-value tests with "too many values to unpack", and the CLI test because the message differs.
• Locally (Python 3.13, zarr 3.4.2, extras dev,notebook,zarr): ruff check . passes, ruff format --check . reports 74 files already formatted, and pytest gives 1469 passed, 1 skipped. The skip is tests/test_discovery.py:665, "running with permissions that ignore file modes" (the run was as root), and is unrelated to this change.

---

Generated by Claude Code