[man4ish]

What

download_references.py writes the pre-contract reference layout (organisms/<common name>/, indexes/<tool>/<name>, dataset_registry.json), and some of its URLs (rat release 112) now 404. The reference tree under /mnt/nas/omnibioai/reference-genomes follows contract v1 (README.md + _schema/ there; validator scripts/reference/validate_reference.py in omnibioai-ecosystem).

main() now refuses with exit code 2 and a pointer to the contract unless --i-know-this-writes-legacy-layout is passed. --help still works.

The guard sits at the top of main(), not at module import, because the test suite imports the module and calls parse_args()/main() directly.

$ python3 download_references.py --status --base-dir <new dir>
download_references.py writes the legacy reference layout (organisms/<common name>/,
indexes/<tool>/<name>, dataset_registry.json), not the contract v1 layout now used under
/mnt/nas/omnibioai/reference-genomes: see README.md and _schema/ there, and
scripts/reference/validate_reference.py in omnibioai-ecosystem.
Refusing to run. Pass --i-know-this-writes-legacy-layout to run it anyway.
rc=2        (base dir not created)

Tests

• Existing CLI tests pass the flag. The two "no selection flag" checks now assert exit code 0, so they can't pass by being refused.
• New test_reference_main_refuses_without_legacy_flag: --status, --scaffold, --dry-run and a bare run all exit 2, the downloader is never constructed, and the base dir is never created.

Local CI

Hosted CI has no budget until 2026-12-01. Full pytest with the repo's pytest.ini, offline (docker run --rm --network none) in obai-workbench:8a1967577087, which provides torch, faiss and sentence-transformers. pytest 8.3.3, pytest-cov 5.0.0 and playwright 1.65.1 come from a local wheel cache; hf_xet is uninstalled as in ci.yml.

	passed	failed	total coverage
this branch	197	6	95.63%
origin/main cdf9ef2	196	6	95.62%

0 new failures. The same 6 fail on both sides in this environment:

• test_coverage_gaps.py::test_reindex_empty_batch_skipped_then_index_dimension_mismatch
• test_coverage_gaps.py::test_reindex_ntotal_mismatch
• test_high_coverage.py::test_reindex_cuda_success_and_validation
• test_high_coverage.py::test_reindex_cuda_error_branches
• test_high_coverage.py::test_reindex_validation_failures
• test_shell_automation.py::test_split_general_corpus_in_temp_copy

The 98% coverage gate fails on both sides here because of those 6. This PR adds no uncovered lines: download_references.py is at 100%, the same as main.

A first run of this branch found 2 tests I had missed (test_download_cli_branches, test_small_remaining_branches). The second commit fixes them, and the numbers above are after that fix.

🤖 Generated with Claude Code