Prepare v2.2.9 release

Author: 1613358894

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v2.2.9 - 2026-06-05
+
+v2.2.9 improves handoff robustness and safe rerun behavior.
+
+### Changed
+
+- Prevent accidental cross-genus reuse of an existing outdir; use
+  `--allow-genus-change` only when intentionally rebuilding an outdir for a
+  different genus.
+- Improve zero accepted checklist guidance by pointing users to
+  `excluded_lpsn_taxa.tsv` instead of guarded downloads.
+- Improve NCBI BioSample transient backend/network failure guidance with
+  retry/cache-based next steps.
+- Expand `package-results --failed-handoff` to include available early
+  acquisition, cache, and diagnostic artifacts.
+- Clarify plan-only run reviews when downloads were not executed.
+
+### Notes
+
+- Normal delivery packaging still requires `manifest.tsv`.
+- `--failed-handoff` only expands optional artifacts in failed-handoff mode.
+
 ## v2.2.8 - 2026-06-04
 
 ### Added

CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use TypeTreeFlow in academic work, please cite this software."
 title: "TypeTreeFlow"
-version: "2.2.8"
-date-released: "2026-06-04"
+version: "2.2.9"
+date-released: "2026-06-05"
 abstract: "A guarded command-line workflow for microbial type-strain genome and 16S phylogeny analysis."
 authors:
   - name: "TypeTreeFlow developers"

README.md

@@ -13,11 +13,11 @@ opt-in flags.
 The long-term goal is to collect auditable type-strain genomes and 16S
 sequences, compare a query genome against references with ANI, build a 16S
 phylogeny, and report reproducible tables, figures, name maps, and summaries.
-The current 2.2.8 release is a small handoff/usability release on top of the
+The current 2.2.9 release is a small handoff/usability release on top of the
 LPSN-first acquisition workflow. It keeps strict evidence boundaries, stable
 I/O contracts, guarded execution, and fake-runner tested wrappers, while making
-manual supplement review, report navigation, failed-run handoff packaging,
-release notes, and install verification easier to follow.
+handoff robustness, safe rerun behavior, failed-run packaging, report
+navigation, release notes, and install verification easier to follow.
 
 GTDB support is retained for legacy/local metadata workflows and as a discovery
 or evidence layer. It is not the authority for species boundaries in the current
@@ -96,7 +96,7 @@ Start with [docs/index.md](docs/index.md) for the full documentation map.
   high-level `doctor`, `verify-genus`, `status`, `next-step`,
   `package-results`, and `verify-release-genus` commands.
 - [docs/release_verification.md](docs/release_verification.md): current
-  release-verification behavior, v2.2.8 failed-handoff notes, reliability
+  release-verification behavior, v2.2.9 handoff/safe-rerun notes, reliability
   history, and gap-report interpretation.
 - [docs/output_layout.md](docs/output_layout.md): canonical output directory
   layout, stage ownership, and path invariants.
@@ -217,7 +217,7 @@ typetreeflow --version
 typetreeflow doctor
 ```
 
-## Recommended v2.2.8 workflow
+## Recommended v2.2.9 workflow
 
 For ordinary users, `verify-genus` is the main entry point. It prepares the
 LPSN-first checklist, NCBI Assembly candidate evidence, optional BioSample
@@ -363,8 +363,9 @@ directories.
 
 When a run fails before `manifest.tsv`, use
 `package-results --failed-handoff` to collect `run_state.json`, selection
-tables, candidate diagnostics, reports if available, and `README_failure.md`.
-Then run `next-step` for specific recovery guidance.
+tables, available early acquisition/cache/diagnostic artifacts, reports if
+available, and `README_failure.md`. Then run `next-step` for specific recovery
+guidance. Normal `package-results` still requires a packageable `manifest.tsv`.
 
 Run the release verification matrix for balanced plus representative policies:
 
@@ -374,25 +375,27 @@ typetreeflow verify-release-genus Fusobacterium \
   --discovery-cache data/fusobacterium_discovery_records.tsv \
   --biosample-cache data/fusobacterium_biosample_records.tsv \
   --enrich-biosample \
-  --outdir results/v2_2_7_release_verification \
+  --outdir results/v2_2_9_release_verification \
   --policies balanced,representative \
   --force
 ```
 
 This writes per-policy outdirs plus
-`results/v2_2_7_release_verification/verification_matrix.tsv` and
+`results/v2_2_9_release_verification/verification_matrix.tsv` and
 `release_verification_summary.md`.
 
-In v2.2.8, `verify-release-genus` retains the v2.2.6 shared acquisition cache:
+In v2.2.9, `verify-release-genus` retains the v2.2.6 shared acquisition cache:
 it writes shared acquisition files under the release outdir and then derives
 the balanced and representative policy outputs from that cache. This avoids
 duplicate LPSN, assembly-discovery, and BioSample queries across policies.
 BioSample enrichment also checkpoints `cache/ncbi/biosample_records.tsv` as
 records are fetched, so an interrupted live enrichment can resume from the
-partial cache instead of starting over. v2.2.8 keeps the handoff wording,
+partial cache instead of starting over. v2.2.9 keeps the handoff wording,
 Clostridium limited smoke notes, release notes, and install reproducibility
-focus, and adds failed-run handoff packaging; it does not expand discovery
-auto-selection or change the evidence model.
+focus, improves failed-run handoff packaging, protects existing outdirs from
+accidental cross-genus reuse unless `--allow-genus-change` is explicit, and
+clarifies plan-only run reviews when downloads were not executed; it does not
+expand discovery auto-selection or change the evidence model.
 
 Selection policy semantics:
 
@@ -475,7 +478,7 @@ rows are not automatically added to `manifest.tsv`, selection rows, completion
 metrics, or evidence levels; curator review is still required before any manual
 selection or registration change.
 
-The v2.2.8 Clostridium limited smoke is only an exploratory verification of
+The v2.2.9 Clostridium limited smoke is only an exploratory verification of
 those guarded handoff and packaging paths. It should use local cache or minimal
 synthetic inputs, should not run real NCBI Datasets downloads, and is not a
 Clostridium genus-completion effort. It does not relax representative-only,

docs/cookbook.md

@@ -121,7 +121,7 @@ typetreeflow verify-release-genus Fusobacterium \
   --discovery-cache data/fusobacterium_discovery_records.tsv \
   --biosample-cache data/fusobacterium_biosample_records.tsv \
   --enrich-biosample \
-  --outdir results/v2_2_7_release_verification \
+  --outdir results/v2_2_9_release_verification \
   --policies balanced,representative \
   --force
 ```
@@ -130,15 +130,16 @@ typetreeflow verify-release-genus Fusobacterium \
 rows are exploratory only and must not be counted as strict type-strain
 completion.
 
-For v2.2.8 reliability checks, `verify-release-genus` keeps the v2.2.6
+For v2.2.9 reliability checks, `verify-release-genus` keeps the v2.2.6
 shared acquisition cache for balanced and representative policies, so LPSN,
 assembly-discovery, and BioSample lookup are not repeated for each policy.
 BioSample enrichment checkpoints `cache/ncbi/biosample_records.tsv` and can
-resume from a partial cache after a network interruption. The v2.2.8 cleanup
+resume from a partial cache after a network interruption. The v2.2.9 cleanup
 keeps the handoff wording, Clostridium limited smoke notes, release notes, and
-install reproducibility focus, and adds failed-run handoff packaging; it does
-not add expanded discovery auto-selection, provider/ATCC auto-download, or
-evidence model changes.
+install reproducibility focus, improves failed-run handoff packaging, protects
+existing outdirs from accidental cross-genus reuse, and clarifies plan-only run
+reviews. It does not add expanded discovery auto-selection, provider/ATCC
+auto-download, or evidence model changes.
 
 Release runs also write auditable gap reports when information is incomplete:
 `completion/gaps.tsv`, `completion/uncovered_species.tsv`, and
@@ -189,7 +190,7 @@ Assembly/BioSample queries in the plan. If expanded discovery is enabled, those
 results are used only for rejected-candidate audit rows and manual supplement
 hints; TypeTreeFlow does not auto-promote a candidate into the manifest.
 
-A Clostridium limited smoke for v2.2.8 should be read the same way: it is a
+A Clostridium limited smoke for v2.2.9 should be read the same way: it is a
 small exploratory cache-based or synthetic run for guarded download planning,
 handoff visibility, status, reports, and packaging. It is not Clostridium genus
 completion, it should not execute real NCBI Datasets downloads, and it does not

docs/index.md

@@ -141,9 +141,9 @@ The repository root currently contains local run outputs and large data under
 documentation map; review them separately before deciding what should remain
 tracked, be regenerated, or be cleaned locally.
 
-## Recommended v2.2.8 Route
+## Recommended v2.2.9 Route
 
-Use README's "Recommended v2.2.8 workflow" section as the shortest current
+Use README's "Recommended v2.2.9 workflow" section as the shortest current
 operator guide and `cookbook.md` as the quick command cookbook. In brief:
 ordinary users should start with `doctor`, run `verify-genus` for plan-only
 review, inspect `selection/user_selection.tsv`, inspect
@@ -158,8 +158,8 @@ barrnap 16S is same-genome/internal evidence; Entrez fallback 16S is opt-in
 external rescue evidence and must be reported separately. See
 `release_verification.md` for current v2.2.x shared acquisition cache,
 checkpoint/resume, package failure explanation, gap-report behavior,
-Clostridium limited smoke notes, and the v2.2.8 release/install and
-failed-handoff focus. External provider planning is metadata/review handoff
+Clostridium limited smoke notes, and the v2.2.9 release/install,
+failed-handoff, and safe-rerun focus. External provider planning is metadata/review handoff
 only; legally obtained local FASTA files enter the workflow through
 `--register-external-genomes`, and provider IDs remain outside NCBI
 `assembly_accession`.

docs/release_notes_v2_2_x.md

@@ -1,6 +1,6 @@
 # v2.2.x Release Notes
 
-These notes consolidate the v2.2.2 through v2.2.8 integration review.
+These notes consolidate the v2.2.2 through v2.2.9 integration review.
 They describe user-visible release-verification behavior only; this document
 does not introduce new workflow features.
 
@@ -54,6 +54,13 @@ does not introduce new workflow features.
 - v2.2.8 adds `package-results --failed-handoff` for failed runs that stop
   before `manifest.tsv`, and improves `next-step` recovery guidance for
   duplicate selected assembly accessions.
+- v2.2.9 improves handoff robustness and safe rerun behavior: cross-genus
+  outdir reuse is blocked unless `--allow-genus-change` is explicit, zero
+  accepted checklist runs point users to `excluded_lpsn_taxa.tsv`, likely
+  transient NCBI BioSample backend/network failures get retry/cache-based next
+  steps, `package-results --failed-handoff` includes available early
+  acquisition/cache/diagnostic artifacts, and plan-only run reviews no longer
+  describe skipped downloads as `0/N` genome coverage.
 
 ## Scientific Boundary
 
@@ -63,7 +70,7 @@ strict, likely type-material, or representative-only evidence boundaries.
 v2.2.5 is published, but complex large-genera representative selection had a
 species-identity limitation that v2.2.6 fixes before auto-selection.
 
-v2.2.8 does not add full Clostridium completion, expanded discovery
+v2.2.9 does not add full Clostridium completion, expanded discovery
 auto-selection, provider/ATCC auto-download, or an evidence model rewrite.
 
 Expanded discovery and taxonomy-derived rows are audit-only. They do not

docs/release_verification.md

@@ -3,6 +3,25 @@
 This page describes the current release-verification contract. It complements
 the historical v2.2.0 matrix runbook in `docs/v2_2_0_release_verification.md`.
 
+## v2.2.9 Handoff and Safe Rerun Notes
+
+v2.2.9 keeps the v2.2.8 failed-handoff and install reproducibility boundaries
+and improves handoff robustness and safe rerun cleanup. Existing outdirs are
+protected from accidental cross-genus reuse unless `--allow-genus-change` is
+explicit. Zero accepted checklist runs point users to `excluded_lpsn_taxa.tsv`;
+likely transient NCBI BioSample backend/network failures point to retry or
+cache-based reruns; failed-handoff packages can include available early
+acquisition, cache, and diagnostic artifacts; and plan-only run reviews do not
+report skipped downloads as `0/N` genome coverage.
+
+Before tagging, confirm package metadata, `typetreeflow.__version__`, CLI
+`--version`, README, release docs, citation metadata, and changelog all report
+`2.2.9`; run final pytest and smoke checks without live downloads.
+
+Normal `package-results` still requires `manifest.tsv`. The extra early
+acquisition/cache/diagnostic artifacts are optional additions only for
+`package-results --failed-handoff`.
+
 ## v2.2.8 Failed-Handoff Notes
 
 v2.2.8 keeps the v2.2.7 limited-smoke and install reproducibility boundaries
@@ -11,10 +30,6 @@ and adds two release-prep handoff refinements: `package-results
 and `next-step` gives specific recovery guidance for duplicate selected
 assembly accessions.
 
-Before tagging, confirm package metadata, `typetreeflow.__version__`, CLI
-`--version`, README, release docs, citation metadata, and changelog all report
-`2.2.8`; run final pytest and smoke checks without live downloads.
-
 ## v2.2.7 Limited Smoke Notes
 
 The v2.2.7 Clostridium limited smoke is exploratory verification only. It uses

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typetreeflow"
-version = "2.2.8"
+version = "2.2.9"
 description = "CLI workflow skeleton for type strain genome and 16S phylogeny analysis."
 readme = "README.md"
 requires-python = ">=3.10"