Prepare v2.2.11 maintenance release

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v2.2.11 - 2026-06-06
+
+v2.2.11 is a maintenance/refactor-only release based on v2.2.10.
+
+### Notes
+
+- No behavior changes.
+- No selection policy changes.
+- No evidence threshold changes.
+- No download strategy changes.
+- No real download validation.
+
 ## v2.2.10 - 2026-06-06
 
 v2.2.10 is a small UX/reporting polish release based on v2.2.9

CITATION.cff

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

README.md

@@ -13,12 +13,10 @@ 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.10 release is a small UX/reporting polish release on top of the
+The current 2.2.11 release is a maintenance/refactor-only 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
-handoff robustness, safe rerun behavior, failed-run packaging, report
-navigation, next-step guidance, taxonomy summaries, package handoffs, release
-notes, and install verification easier to follow.
+I/O contracts, guarded execution, fake-runner tested wrappers, selection
+policies, evidence thresholds, and download strategy unchanged.
 
 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
@@ -97,10 +95,13 @@ 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.10 UX/reporting notes, reliability
+  release-verification behavior, v2.2.11 maintenance notes, reliability
   history, and gap-report interpretation.
 - [docs/output_layout.md](docs/output_layout.md): canonical output directory
   layout, stage ownership, and path invariants.
+- [docs/handoff_index_contract.md](docs/handoff_index_contract.md): how to
+  interpret generated `handoff_index.md` files as package navigation/status
+  summaries, not scientific decision sources.
 - [docs/schemas.md](docs/schemas.md): TSV and table field dictionary.
 - [docs/statuses.md](docs/statuses.md): emitted status values and meanings.
 - [docs/design.md](docs/design.md): current architecture and safety contract.
@@ -218,7 +219,7 @@ typetreeflow --version
 typetreeflow doctor
 ```
 
-## Recommended v2.2.10 workflow
+## Recommended v2.2.11 workflow
 
 For ordinary users, `verify-genus` is the main entry point. It prepares the
 LPSN-first checklist, NCBI Assembly candidate evidence, optional BioSample

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_10_release_verification \
+  --outdir results/v2_2_11_release_verification \
   --policies balanced,representative \
   --force
 ```
@@ -130,19 +130,13 @@ typetreeflow verify-release-genus Fusobacterium \
 rows are exploratory only and must not be counted as strict type-strain
 completion.
 
-For v2.2.10 reliability checks, `verify-release-genus` keeps the v2.2.6
+For v2.2.11 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.10 cleanup
-keeps the handoff wording, Clostridium limited smoke notes, release notes, and
-install reproducibility focus, improves failed-run handoff packaging, protects
-existing outdirs from accidental cross-genus reuse, clarifies plan-only run
-reviews, improves next-step guidance, clarifies taxonomy summaries, and writes
-`handoff_index.md` in package handoffs. It does not add expanded discovery
-auto-selection, provider/ATCC auto-download, download-strategy changes,
-selection-safety changes, evidence-threshold changes, or evidence model
-changes.
+resume from a partial cache after a network interruption. See
+`release_verification.md` and `release_notes_v2_2_x.md` for the v2.2.11
+maintenance scope; the cookbook keeps only the runnable command path here.
 
 Release runs also write auditable gap reports when information is incomplete:
 `completion/gaps.tsv`, `completion/uncovered_species.tsv`, and

docs/handoff_index_contract.md

@@ -0,0 +1,77 @@
+# Handoff Index Contract
+
+`handoff_index.md` is the delivery-package navigation index and status summary
+written by `package-results`. It helps a downstream reviewer find the files
+copied into a successful delivery package or failed-run handoff package, see
+the recorded workflow/package status, and identify the next operational review
+step. Like the delivery package itself, it is not a cache mirror.
+
+`handoff_index.md` is not a new scientific decision source. It does not replace
+row-level TSV evidence, report detail, source-audit records, completion audit
+records, or curator review. It summarizes already recorded package state and
+points users back to the files that remain authoritative for scientific,
+audit, and completion interpretation.
+
+## Authoritative Sources
+
+Use these files as the scientific and audit sources of record when they are
+present:
+
+- `manifest.tsv`
+- `source_audit/sequence_source_audit.tsv`
+- `source_audit/completion_audit.tsv`
+- `completion/*.tsv`
+- `report/summary.md`
+- `report/run_review.md`
+
+The handoff index can quote counts, status labels, warning summaries, included
+file names, missing optional files, and a recommended next step from the same
+run, but those summaries are navigation aids. If a count or conclusion matters
+for publication, release verification, or downstream curation, cite and inspect
+the authoritative source file directly.
+
+## Successful And Failed Handoffs
+
+A successful handoff is produced by normal `package-results` after
+`manifest.tsv` exists. Its `handoff_index.md` identifies the package as a
+`successful completion handoff`, lists copied files, reports included genome,
+16S, report, selection, and download-status summaries, and keeps evidence
+caveats visible.
+
+A failed handoff is produced by `package-results --failed-handoff`, including
+for runs that stopped before `manifest.tsv` existed. Its `handoff_index.md`
+states that it is a failed-run handoff package and not a successful completion
+package. It may include partial run state, selection, acquisition, cache,
+diagnostic, completion-hint, and report artifacts for review or recovery
+planning. A failed handoff must not be read as successful completion, strict
+type-strain completion, or validated downstream readiness.
+
+## Next Action And Warning Fields
+
+`next action`, `Recommended Next Step`, fallback warning summaries, and source
+audit warning summaries are operational guidance. They tell the reviewer what
+to inspect or retry next and which caveats deserve attention. They are not
+scientific conclusions, taxonomic decisions, strict evidence upgrades, or
+completion overrides.
+
+For example, an Entrez fallback warning can make a practical 16S availability
+issue visible, but it does not make Entrez fallback evidence equivalent to
+same-genome barrnap evidence. A representative-only row can be useful for
+exploration, but it remains outside strict type-strain completion.
+
+## Downstream Use
+
+Downstream users should cite `handoff_index.md` only as a package navigation
+and status-summary file. Use it to answer questions such as:
+
+- Which package type was produced?
+- Which files were copied into the handoff package?
+- Was this a successful handoff or a failed-run review package?
+- Which report, audit, completion, or manifest files should be inspected next?
+- What operational next step or warning summary did the package record?
+
+Do not cite `handoff_index.md` alone for scientific statements such as a final
+species coverage claim, type-strain confirmation, same-genome 16S support,
+completion audit result, or curator acceptance. For those claims, cite the
+relevant authoritative source files listed above, with `handoff_index.md` used
+only as the navigation entry point when helpful.

docs/index.md

@@ -13,6 +13,9 @@ move, archive, or deletion.
   workflow surface.
 - [output_layout.md](output_layout.md): Canonical output directory and file
   layout. Treat as the path contract for runs, tests, and downstream users.
+- [handoff_index_contract.md](handoff_index_contract.md): Contract for
+  interpreting generated delivery-package `handoff_index.md` files as package
+  navigation and status summaries, not new scientific decision sources.
 - [schemas.md](schemas.md): TSV and table field dictionary. Use
   `output_layout.md` for paths and stage ownership; use this document for
   field-level contracts.
@@ -141,25 +144,15 @@ 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.10 Route
-
-Use README's "Recommended v2.2.10 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
-`completion/manual_supplement_hints.tsv` when present, use `status` or
-`next-step` for the next handoff action, register external FASTA only after
-curator review, and use `package-results` for handoff. Use
-`--auto-accept-selection --enable-downloads` only after accepting the generated
-selection. Resume existing outdirs with `--resume` or `--continue`.
-`verify-release-genus` is the release-matrix wrapper for balanced and
-representative verification. Representative selection is exploratory only.
-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.10 release/install,
-failed-handoff, safe-rerun, UX/reporting, and package-handoff focus. External provider planning is metadata/review handoff
-only; legally obtained local FASTA files enter the workflow through
+## Recommended v2.2.11 Route
+
+Use README's "Recommended v2.2.11 workflow" section as the current operator
+guide and `cookbook.md` as the quick command cookbook. See
+`release_verification.md` for the release-verification route, including
+`verify-release-genus`, shared acquisition cache, checkpoint/resume,
+gap-report behavior, and the v2.2.11 maintenance release focus.
+
+External provider planning remains 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/output_layout.md

@@ -88,6 +88,7 @@ typetreeflow_out/
     figures/
   delivery/
     README.md
+    handoff_index.md
     manifest.tsv
     run_state.json
     selected_accessions.tsv
@@ -215,6 +216,17 @@ evidence summaries when present, download results when present, optional
 reports, genome FASTA files, and optional 16S FASTA files. They do not copy
 credentials, `.env` files, API keys, NCBI Datasets ZIP caches, pytest caches,
 temporary directories, or provider credentials.
+`delivery/handoff_index.md` is the package navigation index and status summary.
+It is not a new scientific decision source; authoritative scientific and audit
+interpretation remains with `manifest.tsv`,
+`source_audit/sequence_source_audit.tsv`,
+`source_audit/completion_audit.tsv`, `completion/*.tsv`, `report/summary.md`,
+and `report/run_review.md`. See
+[handoff_index_contract.md](handoff_index_contract.md).
+Failed-run review packages created with `package-results --failed-handoff`
+write `failed_handoff/handoff_index.md` plus `README_failure.md` and available
+partial review artifacts. These packages are explicitly not successful
+completion handoffs.
 
 Resume behavior reuses durable artifacts in this order: an installed
 `genomes/references/<normalized_id>.fna`, an existing extracted directory under

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.10 integration review.
+These notes consolidate the v2.2.2 through v2.2.11 integration review.
 They describe user-visible release-verification behavior only; this document
 does not introduce new workflow features.
 
@@ -66,6 +66,9 @@ does not introduce new workflow features.
   completion, plan-only `next-step` prioritizes selection review and guarded
   downloads, taxonomy enrichment summaries clarify offline scaffold/cache-only
   runs, and `package-results` writes `handoff_index.md`.
+- v2.2.11 is a maintenance/refactor-only release. It changes no selection
+  policy, evidence threshold, download strategy, real download validation, or
+  user-visible workflow behavior.
 
 ## Scientific Boundary
 
@@ -75,7 +78,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.10 does not add full Clostridium completion, expanded discovery
+v2.2.11 does not add full Clostridium completion, expanded discovery
 auto-selection, provider/ATCC auto-download, or an evidence model rewrite.
 It does not change download strategy, selection safety, or evidence thresholds.
 

docs/release_verification.md

@@ -3,6 +3,16 @@
 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.11 Maintenance Notes
+
+v2.2.11 is a maintenance/refactor-only release. It keeps v2.2.10 behavior,
+selection policies, evidence thresholds, download strategy, and guarded
+execution boundaries unchanged. It does not include real download validation.
+
+Before tagging, confirm package metadata, `typetreeflow.__version__`, CLI
+`--version`, README, release docs, citation metadata, and changelog all report
+`2.2.11`; run final pytest and smoke checks without live downloads.
+
 ## v2.2.10 UX and Reporting Notes
 
 v2.2.10 keeps the v2.2.9 safe-rerun, failed-handoff, and install
@@ -12,10 +22,6 @@ fallback completion; plan-only `next-step` prioritizes selection review and
 guarded downloads; taxonomy enrichment summaries distinguish offline scaffold
 and cache-only runs; and `package-results` writes `handoff_index.md`.
 
-Before tagging, confirm package metadata, `typetreeflow.__version__`, CLI
-`--version`, README, release docs, citation metadata, and changelog all report
-`2.2.10`; run final pytest and smoke checks without live downloads.
-
 v2.2.10 does not change download strategy, selection safety, or evidence
 thresholds.
 

pyproject.toml

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

tests/test_docs_consistency.py

@@ -81,7 +81,7 @@ def test_release_version_sources_are_consistent():
     release_notes = _read("docs/release_notes_v2_2_x.md")
 
     version = typetreeflow.__version__
-    assert version == "2.2.10"
+    assert version == "2.2.11"
     assert f'version = "{version}"' in pyproject
     assert f"## v{version} - 2026-06-06" in changelog
     assert f"current {version} release" in readme
@@ -601,6 +601,44 @@ def test_v2_2_x_release_docs_are_discoverable():
         assert phrase in acceptance_checklist
 
 
+def test_handoff_index_contract_is_discoverable_and_preserves_boundaries():
+    contract = _read("docs/handoff_index_contract.md")
+    index = _read("docs/index.md")
+    output_layout = _read("docs/output_layout.md")
+    readme = _read("README.md")
+    normalized_contract = _normalize_whitespace(contract)
+    normalized_output_layout = _normalize_whitespace(output_layout)
+
+    assert "handoff_index_contract.md" in index
+    assert "handoff_index_contract.md" in output_layout
+    assert "handoff_index_contract.md" in readme
+
+    for phrase in [
+        "delivery-package navigation index and status summary",
+        "not a new scientific decision source",
+        "`manifest.tsv`",
+        "`source_audit/sequence_source_audit.tsv`",
+        "`source_audit/completion_audit.tsv`",
+        "`completion/*.tsv`",
+        "`report/summary.md`",
+        "`report/run_review.md`",
+        "`successful completion handoff`",
+        "failed-run handoff package and not a successful completion package",
+        "operational guidance",
+        "not scientific conclusions",
+        "not a cache mirror",
+    ]:
+        assert phrase in normalized_contract
+
+    for phrase in [
+        "not a new scientific decision source",
+        "authoritative scientific and audit interpretation remains with",
+        "Failed-run review packages",
+        "not successful completion handoffs",
+    ]:
+        assert phrase in normalized_output_layout
+
+
 def test_v1_5_provider_and_local_artifact_docs_preserve_review_boundaries():
     readme = _read("README.md")
     index = _read("docs/index.md")
@@ -656,5 +694,9 @@ def _read(path: str) -> str:
         return handle.read()
 
 
+def _normalize_whitespace(text: str) -> str:
+    return " ".join(text.split())
+
+
 def _header(path: str) -> list[str]:
     return _read(path).splitlines()[0].split("\t")