bioflowkit 0.2.0__tar.gz → 0.3.0__tar.gz

bioflowkit-0.3.0/.gitattributes

@@ -0,0 +1,20 @@
+# Test fixtures are read by Linux containers (FastANI, CAFE5, …).  Some
+# tool parsers don't strip a stray CR, so a CRLF checkout on Windows
+# silently corrupts them (CAFE5 read the last column header as "D\r" and
+# reported "D was not found").  Force LF for text fixtures everywhere,
+# and mark the compressed reads binary so git never touches them.
+data/test/**/*.fna   text eol=lf
+data/test/**/*.fa    text eol=lf
+data/test/**/*.fasta text eol=lf
+data/test/**/*.tsv   text eol=lf
+data/test/**/*.csv   text eol=lf
+data/test/**/*.nwk   text eol=lf
+data/test/**/*.txt   text eol=lf
+data/test/**/*.gff   text eol=lf
+data/test/**/*.ffn   text eol=lf
+data/test/**/*.gz    binary
+
+# Registry + recipe shell commands also end up inside Linux containers;
+# keep them LF regardless of host.
+*.yaml text eol=lf
+registry/** text eol=lf

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/.github/workflows/candidate-smoke-test.yml

@@ -17,6 +17,11 @@ permissions:
   contents: read
   pull-requests: write   # for the summary comment
 
+# Opt into the Node 24 runtime ahead of the 2026-06-16 forced switch so
+# the v4/v5 actions stop emitting Node 20 deprecation warnings.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   smoke:
     name: Validate + smoke-test changed candidates

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/.github/workflows/ci.yml

@@ -6,6 +6,11 @@ on:
   pull_request:
     branches: [main]
 
+# Opt into the Node 24 runtime ahead of the 2026-06-16 forced switch so
+# the v4/v5 actions stop emitting Node 20 deprecation warnings.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   unit-tests:
     name: Unit tests (Python ${{ matrix.python-version }})
@@ -47,12 +52,11 @@ jobs:
         run: ruff check .
 
   typecheck:
-    # Advisory only — mypy issues do not block merging.  Provides
-    # visibility while we gradually add type annotations.  Will be
-    # upgraded to a blocking check when the error count reaches 0.
-    name: Type check (mypy, advisory)
+    # Blocking: the bioflow package type-checks clean under mypy
+    # (--ignore-missing-imports for the un-stubbed docker / anthropic /
+    # openai SDKs).  Keep it that way — a new type error fails CI.
+    name: Type check (mypy)
     runs-on: ubuntu-latest
-    continue-on-error: true
 
     steps:
       - uses: actions/checkout@v4
@@ -66,7 +70,7 @@ jobs:
         run: pip install -e ".[dev]" && pip install types-PyYAML types-requests
 
       - name: Run mypy
-        run: mypy bioflow --ignore-missing-imports || true
+        run: mypy bioflow --ignore-missing-imports
 
   registry-schema:
     name: Validate registry YAMLs
@@ -108,12 +112,12 @@ jobs:
           EOF
 
   digest-audit:
-    # Advisory until enough tools are pinned — prints the missing-digest
-    # count and lists the first ~30 unpinned tools.  Upgrade to a blocking
-    # check (drop `|| true`) once the bulk of the registry is pinned.
-    name: Container digest pin audit (advisory)
+    # Now blocking: every *active* tool must carry an image_digest
+    # (deprecated tools are skipped — their upstream images are gone by
+    # definition).  This keeps the registry fully content-addressed so a
+    # silently-retagged or GC'd upstream image can never change results.
+    name: Container digest pin audit
     runs-on: ubuntu-latest
-    continue-on-error: true
 
     steps:
       - uses: actions/checkout@v4
@@ -126,5 +130,5 @@ jobs:
       - name: Install dependencies
         run: pip install pyyaml
 
-      - name: Count missing image_digest entries
-        run: python scripts/pin_digests.py --audit || true
+      - name: Require every active tool to be digest-pinned
+        run: python scripts/pin_digests.py --audit

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/.github/workflows/docs.yml

@@ -26,6 +26,11 @@ concurrency:
   group: pages
   cancel-in-progress: true
 
+# Opt into the Node 24 runtime ahead of the 2026-06-16 forced switch so
+# the v3/v4/v5 actions stop emitting Node 20 deprecation warnings.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   build:
     runs-on: ubuntu-latest

bioflowkit-0.3.0/.github/workflows/nfcore-concordance.yml

@@ -0,0 +1,75 @@
+name: nf-core concordance
+
+# Manually-dispatched concordance benchmark: run bioflow and the matching
+# nf-core pipeline on a golden dataset, then score their agreement with
+# scripts/compare_nfcore.py.
+#
+# This is NOT a per-PR gate.  A real run needs tens of GB of references
+# and hours of compute, so it expects a runner that already has them
+# staged (a self-hosted runner, or a large GitHub runner the maintainer
+# provisions).  It is run deliberately before a release and its JSON
+# output is published with the release notes.
+#
+# See docs/benchmarks/nfcore-concordance.md for the datasets, method, and
+# acceptance thresholds.
+
+on:
+  workflow_dispatch:
+    inputs:
+      comparison:
+        description: "Which comparison to run"
+        type: choice
+        options: [vcf, counts]
+        default: vcf
+      bioflow_output:
+        description: "Path to the bioflow output (VCF or counts TSV) on the runner"
+        required: true
+      reference_output:
+        description: "Path to the nf-core output on the runner"
+        required: true
+      threshold:
+        description: "Min Jaccard (vcf) or Spearman rho (counts) to pass"
+        required: false
+        default: "0.90"
+
+# Opt into the Node 24 runtime ahead of the 2026-06-16 forced switch.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  score:
+    name: Score concordance
+    # The default GitHub runner cannot hold iGenomes references; point this
+    # at a self-hosted runner that has them staged.  Left as ubuntu-latest
+    # so the workflow is valid and the *scoring* step is exercisable on
+    # pre-staged outputs.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Score bioflow vs nf-core
+        run: |
+          if [ "${{ inputs.comparison }}" = "vcf" ]; then
+            python scripts/compare_nfcore.py vcf \
+              --bioflow "${{ inputs.bioflow_output }}" \
+              --reference "${{ inputs.reference_output }}" \
+              --out concordance.json \
+              --min-jaccard "${{ inputs.threshold }}"
+          else
+            python scripts/compare_nfcore.py counts \
+              --bioflow "${{ inputs.bioflow_output }}" \
+              --reference "${{ inputs.reference_output }}" \
+              --out concordance.json \
+              --min-rho "${{ inputs.threshold }}"
+          fi
+
+      - name: Upload concordance report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: nfcore-concordance
+          path: concordance.json

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/.github/workflows/nightly-smoke.yml

@@ -10,6 +10,11 @@ on:
     - cron: "0 3 * * *"
   workflow_dispatch:
 
+# Opt into the Node 24 runtime ahead of the 2026-06-16 forced switch so
+# the v4/v5 actions stop emitting Node 20 deprecation warnings.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   smoke-matrix:
     name: Recipe smoke matrix
@@ -43,12 +48,20 @@ jobs:
             -v -m docker \
             --junitxml=reports/smoke.xml
 
-      - name: Upload junit report
+      - name: Run full-pipeline e2e (all 9 recipes with committed fixtures)
+        env:
+          BIOFLOW_LOG_LEVEL: INFO
+        run: |
+          python -m pytest tests/integration/test_full_pipeline_e2e.py \
+            -v -m docker \
+            --junitxml=reports/full_e2e.xml
+
+      - name: Upload junit reports
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: smoke-junit
-          path: reports/smoke.xml
+          path: reports/*.xml
 
       - name: Fail the job on red results
         if: failure()

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/.github/workflows/release.yml

@@ -22,6 +22,11 @@ on:
 permissions:
   contents: read
 
+# Opt into the Node 24 runtime ahead of the 2026-06-16 forced switch so
+# the v4/v5 actions stop emitting Node 20 deprecation warnings.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   build:
     name: Build sdist + wheel

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/.gitignore

@@ -98,3 +98,4 @@ build/
 
 # MkDocs build output
 site/
+data/test/**/_e2e_out/

{bioflowkit-0.2.0 → bioflowkit-0.3.0}/CHANGELOG.md

@@ -12,6 +12,391 @@ ship bug fixes only.  Breaking changes to the documented public API
 
 ---
 
+## [Unreleased]
+
+## [0.3.0] — 2026-06-18
+
+### Fixed — aligner images had no samtools (5 recipes broke at alignment)
+The plain single-tool aligner BioContainers (`bwa`, `bowtie2`,
+`minimap2`) do **not** bundle samtools, yet five recipes ran
+`aligner | samtools sort` / `samtools index` inside them — so every one
+failed at its alignment stage with `samtools: command not found`.  The
+smoke matrix only exercises each recipe's *first* stage, so this stayed
+invisible.  (See #2.)  Each aligner stage now uses an image that carries
+both tools:
+- **germline_variants**, **joint_genotyping**: a mulled
+  `bwa 0.7.19 + samtools 1.22` image.  A new **`prepare_reference`**
+  stage builds the BWA index + `.fai` + `.dict` **once** (in the cohort
+  recipe, before the per-sample fan-out — previously each parallel
+  sample raced to index the *shared* reference), and the gatk call stage
+  drops its own `samtools` calls (`MarkDuplicates --CREATE_INDEX`
+  indexes the dedup BAM; the gatk4 image ships no samtools either).
+  Verified end-to-end on phiX: prep → bwa-mem → sort/index →
+  MarkDuplicates → HaplotypeCaller now produces a valid VCF.
+- **chip_seq**, **atac_seq**: `staphb/bowtie2:2.5.4` (bundles samtools).
+- **metagenome_assembly**: a mulled `minimap2 2.31 + samtools 1.23` image.
+- `registry/tools/alignment/bowtie2.yaml` had the same broken
+  assumption (and `samtools.yaml` documented it as fact) — both fixed.
+
+### Fixed — static audit of the never-e2e'd recipes (round 1)
+A static pass over the 10 recipes that have no committed full-e2e fixture
+(they need external reference data) turned up several latent defects:
+- **proteomics_dda**: the percolator FDR cut used ``awk -F\t``, whose
+  backslash bash strips before awk sees it — so the field separator
+  became the literal letter ``t`` instead of a tab, and
+  ``passing_psms.tsv`` was filtered on garbage columns.  Now ``-F"\t"``,
+  which reaches awk as a real tab (verified).
+- **eukaryote_assembly**: the docstring advertised ``polish=False`` to
+  skip Medaka for HiFi reads, but no such parameter existed.  Added it
+  (the ``polish`` stage is renamed ``polish_consensus`` to free the
+  name); ``assess`` already falls back to Flye's ``assembly.fasta``.
+- **chip_seq**: docstring promised ``--ctrl-r1 / --ctrl-r2`` raw-control
+  alignment the recipe never implemented — corrected to document the
+  actual ``--ctrl-bam`` (pre-aligned control) input.
+- **metagenomics_profile**: ``bioflow db fetch`` example used a
+  catalog key that doesn't exist (``kraken2_standard`` →
+  ``kraken2_standard_8gb``) and now notes Bracken's ``kmer_distrib`` need.
+
+### Docs — strict build fixed + e2e-coverage page
+- `mkdocs build --strict` was aborting: three docs links pointed at repo
+  files outside the `docs/` tree (`conda-recipe/meta.yaml`,
+  `scripts/compare_nfcore.py`, the nf-core workflow), which strict mode
+  flags as unresolved.  Re-pointed them at GitHub blob URLs.
+- New **`reference/e2e-coverage.md`** documents which 9 recipes have a
+  committed full end-to-end fixture and which 10 are gated on external
+  reference data (with the `bioflow db fetch` key for each), plus the one
+  utility recipe.  Regenerated `reference/recipes.md` / `tools.md` from
+  the registry (now 20 recipes; `joint_genotyping` was missing and image
+  tags were stale).
+
+### Fixed — ani_matrix broken for genomes outside the workspace
+- **Bug a full e2e caught**: FastANI reads genome paths from a *list
+  file*, not the command, so the SDK's command-path translator and
+  auto-mount never applied to them — every external genome failed with
+  `Could not open <host path>`.  Since genomes normally live outside the
+  output workspace, this broke the recipe's primary documented use.
+- New SDK helper **`stage_input(path)`** copies an external file into the
+  active workspace (always mounted at `/work`) and returns its container
+  path — the clean primitive for any recipe that feeds a tool a list
+  file of paths.  Also exported **`container_path(path)`**.
+- `ani_matrix` now stages genomes via `stage_input` and writes container
+  paths into the FastANI list; verified end-to-end (genome1 vs genome2 =
+  99.5% ANI).
+
+### Added — full e2e for the comparative-genomics recipes
+- `tests/integration/test_full_pipeline_e2e.py` gains real end-to-end
+  tests for **amr_vf_catalogue** (ABRicate fan-out, bundled DBs),
+  **ani_matrix** (all-vs-all FastANI), **pangenome** (Prokka × N →
+  Roary), and **gwas** (Scoary on a synthetic Roary GPA + phenotype,
+  recovers a planted association).  Fixtures:
+  `data/test/genomes_small/` (phiX174 + a 25-SNP variant) and
+  `data/test/gwas_small/` (12-gene × 10-sample GPA).  Recipes validated
+  end-to-end: 1 (prokaryote) → 9 (see below).
+- **cafe_evolution** (CAFE5 gene-family expansion/contraction) added as
+  the 6th, on `data/test/cafe_small/` (ultrametric 4-taxon tree + 60
+  families).
+- **phylogeny** (single-copy core → MAFFT × N → IQ-TREE) added as the
+  7th, on `data/test/phylo_small/` (Prokka GFF + CDS + Roary GPA for 4
+  phiX strains; IQ-TREE recovers a 4-taxon ML tree).
+- **rnaseq_deg** (fastp → Salmon → DESeq2 → enrichment + MultiQC) added
+  as the 8th, on `data/test/rnaseq_small/` (60 synthetic transcripts, 4
+  samples, 10 transcripts planted ~4× up in the treated group).  DESeq2
+  recovers the planted signal (`tx0001` log2FC ≈ 2) and the run finishes
+  in seconds.  The sample sheet is built by the test at run time so no
+  machine-specific paths are committed.
+- **methylation_wgbs** (TrimGalore → Bismark → methylKit) added as the
+  9th, on `data/test/methyl_small/` (phiX174 + 3,000 synthetic
+  directional bisulfite read pairs, ~70 % CpG-methylated).  The reads
+  map at 100 % and Bismark produces a real cytosine report; the genome
+  is **not** committed pre-prepared — the new `bismark_prep` stage
+  (below) bisulfite-converts it at run time, so no version-tied bowtie2
+  index lands in git.  Regenerated deterministically by
+  `scripts/gen_methyl_fixture.py`.
+
+### Added — methylation_wgbs prepares its genome (matches the docs)
+- The recipe's docstring promised automatic genome preparation, but the
+  pipeline had no such stage — it silently required a pre-prepared
+  `Bisulfite_Genome/` directory, so running from a plain reference FASTA
+  failed.  A new **`bismark_prep`** stage now runs
+  `bismark_genome_preparation` when `--bismark-genome` is a FASTA (or a
+  directory holding one); an already-prepared directory is detected and
+  used directly, skipping preparation.  `methylation_wgbs` is now 4
+  stages (trim → bismark_prep → bismark → methylkit).
+
+### Fixed — methylKit CpG-report glob (shell ate the regex escape)
+- `methylkit_dmr` matched the cytosine report with `pattern='…txt(\.gz)?$'`,
+  but the `\.` escape was stripped by the shell before R parsed the
+  string, so R aborted with *"'\.' is an unrecognized escape in character
+  string"* and the whole recipe failed at the final stage.  Replaced with
+  a `[.]` character class (no backslash to escape), which matches the
+  report — with or without a `.gz` suffix — robustly.
+
+### Fixed — rnaseq_deg DESeq2 step (two latent bugs)
+- The `deseq2_diff` stage required **tximport**, which the
+  `bioconductor-deseq2` BioContainer does not ship — every run failed
+  with "there is no package called 'tximport'".  Rewritten to assemble
+  the count matrix in base R straight from each sample's `quant.sf`
+  (`NumReads`, rounded) and feed `DESeqDataSetFromMatrix`, dropping the
+  tximport dependency entirely.
+- A second, masked bug: `samples$sample_id` inside the `Rscript -e "…"`
+  body (run via `sh -c`) was shell-expanded because the `$` was
+  unescaped, so the `file.path(...)` of `quant.sf` paths was wrong.
+  Escaped to `\$sample_id`.  The pipeline now also **fails fast** if the
+  DESeq2 stage exits non-zero (the downstream Enrichr step tolerates an
+  empty gene list, which previously masked a broken DEG table).
+
+### Fixed — LF line endings for container-read fixtures
+- A new `.gitattributes` pins text test fixtures (and registry YAMLs) to
+  LF.  CAFE5 doesn't strip a trailing CR, so a CRLF checkout on Windows
+  made it read the last species column as `D\r` and fail with "D was not
+  found in gene family …".  FASTA parsers tolerated the CR, but the
+  table parser did not — LF is now enforced so fixtures are safe on
+  every host.
+
+### Fixed — bounded stdout retention (no orchestrator OOM on chatty tools)
+- `DockerBackend.run` accumulated **every** stdout line in memory; a
+  tool that emits millions of lines (Roary, IQ-TREE) could OOM the
+  orchestrator.  It now retains only the trailing `_STDOUT_TAIL_LINES`
+  (5000) via a bounded `deque` for the diagnostic `CommandResult.stdout`
+  — every line still streams live to `log_callback`, and real artifacts
+  go to files in the workspace.
+- Tests: +1 (`test_docker_timeout.py`) asserting the tail is kept.
+
+### Fixed — clear error for shell-unsafe external input filenames
+- An external input file whose **basename** contained a space or shell
+  metacharacter silently corrupted the recipe's command — bioflow mounts
+  the file's parent at the space-free `/inputs/<n>` and splices the
+  basename in unquoted, and it can't be quoted generically because many
+  recipes wrap the whole command in `bash -c '…'`.  (A spaced *directory*
+  was already fine — only the basename survives into the command.)
+- `_collect_external_mounts` now raises an actionable `ValueError`
+  naming the offending characters and telling the user to rename /
+  symlink to a safe name.
+- Tests: +12 (`tests/unit/test_unsafe_paths.py`), incl. confirmation
+  that spaced *directories* and workspace-internal paths are unaffected.
+
+### Fixed — stage_timeout now actually bounds runtime
+- **Latent bug**: `run_plan(stage_timeout=…)` never worked.  The log
+  loop (`container.logs(stream=True, follow=True)`) blocks until the
+  container exits, so the subsequent `container.wait(timeout=…)` — a
+  docker-py HTTP read timeout, not a runtime cap — could never fire for
+  a runaway container; it would hang forever.
+- `DockerBackend.run` now starts a watchdog `threading.Timer` that
+  `container.kill()`s the stage when the timeout elapses, returning the
+  conventional exit code **124** with a clear message.
+- Tests: +3 (`tests/unit/test_docker_timeout.py`, fake-container based,
+  deterministic).
+
+### Fixed — DockerBackend now clamps CPU/RAM to host capacity
+- **Bug the full-pipeline e2e caught**: a stage declaring `cpu=8` (e.g.
+  SPAdes in `prokaryote_assembly`) failed to even *start* on any host
+  with fewer cores — Docker rejects a container whose `--cpus` exceeds
+  the host count ("range of CPUs is from 0.01 to N.00"), so all 3 retry
+  attempts died instantly.  Passed locally (12 cores) but failed on the
+  4-core CI runner — and would hit any user on a small workstation.
+- `DockerBackend.run` now clamps the requested CPU to the host core count
+  and RAM to ~90% of host memory (`_clamp_resources`), so an
+  over-ambitious resource request degrades to "use what's available"
+  instead of crashing.
+- Tests: +5 (`tests/unit/test_resource_clamp.py`).
+
+### Added — first full-pipeline end-to-end test
+- `tests/integration/test_full_pipeline_e2e.py`: runs the **entire**
+  `prokaryote_assembly` recipe (fastp → SPAdes → QUAST → Prokka) against
+  real BioContainers — the first time a complete pipeline (not just a
+  first stage, as the smoke matrix does) is validated end-to-end.
+- New `data/test/phix_small/` fixture: phiX174 (`NC_001422.1`, 5386 bp) +
+  1000 wgsim-simulated 150 bp pairs (~56×, seed 42 → deterministic).
+  phiX assembles into a single ~5.4 kb contig in <1 min, so the whole
+  chain finishes in ~45 s.
+- Asserts real data flow: assembled contig length 4.5–6 kb, QUAST
+  `report.tsv`, and Prokka annotation with ≥1 CDS.  Verified locally
+  (phiX → 1 contig 5377 bp, 6 CDS).
+- Wired into the nightly-smoke workflow as a second step.
+
+## [0.2.1] — 2026-06-12
+
+> **Why upgrade from 0.2.0**: the `v0.2.0` tag predated the registry
+> freshness fix, so the 0.2.0 wheel bundled a registry whose
+> `quay.io/biocontainers/*` tags had been garbage-collected from Quay —
+> `rnaseq_deg`, `chip_seq`, `atac_seq`, `eukaryote_assembly`,
+> `metagenome_assembly`, and others would fail at run time with "image
+> not found".  **0.2.1 ships the repaired, 107/107-pinned registry**, so
+> recipes actually pull their containers.  Everything below landed after
+> the 0.2.0 cut and is new to PyPI users here.
+
+### Changed — nightly smoke matrix expanded (3 → 5 recipes)
+- Added real-container smoke cases for **chip_seq** (TrimGalore — a
+  container family shared by chip/atac/methylation, previously
+  unexercised) and **germline_variants** (validates the variant recipe's
+  fastp wiring).  All five pass against real BioContainers locally
+  (~90 s) — more of the "522 mostly-mock tests" critique closed with
+  genuine end-to-end coverage.
+
+### Changed — mypy type-checking is now blocking
+- Fixed all 33 mypy errors across 7 modules (Rich `TaskID` optionals in
+  the progress bars, `dict[str, Any]` run kwargs, anthropic/openai/docker
+  SDK union + missing-stub noise, a loop-variable shadow in
+  `cli/update.py`).  `mypy bioflow --ignore-missing-imports` now reports
+  **0 errors**.
+- CI's `typecheck` job drops `continue-on-error` — a new type error now
+  fails the build, closing the "advisory only" gap.
+
+### Added — nf-core concordance benchmark (harness + methodology)
+- `scripts/compare_nfcore.py` (new, stdlib-only): scores agreement
+  between a bioflow output and the matching nf-core output —
+  **Jaccard + genotype concordance** on normalised VCF sites
+  (vs nf-core/sarek), and **Spearman ρ** of per-gene counts
+  (vs nf-core/rnaseq).  Optional `--min-jaccard` / `--min-rho` gate for
+  CI.
+- `docs/benchmarks/nfcore-concordance.md`: golden datasets
+  (GIAB HG002 chr20; nf-core/rnaseq chr22), method, and initial
+  acceptance thresholds.
+- `.github/workflows/nfcore-concordance.yml`: manually-dispatched job
+  (not a per-PR gate — a full run needs staged references).
+- Honesty note: bioflow ships the *scoring* half (committed + tested);
+  the *production* half (running both pipelines on a machine with the
+  references) is operator-run and documented.
+- Tests: +13 (`tests/unit/test_compare_nfcore.py`).
+
+### Added — GPU passthrough + Podman runtime
+- `@stage(..., gpu=True)` (and a tool YAML's `resources.gpu`) now attach
+  all host GPUs to that stage's container via a Docker `DeviceRequest`
+  (the API equivalent of `--gpus all`); needs the NVIDIA Container
+  Toolkit, and degrades to a warning on CPU-only hosts rather than
+  failing.  Threaded through `Stage`, the `@stage` decorator, and the
+  preset `run_plan` path.
+- `DockerBackend` works with **Podman**: it honours `BIOFLOW_DOCKER_HOST`
+  / `DOCKER_HOST` (point it at the Podman API socket) and an optional
+  `base_url`, and reads `BIOFLOW_CONTAINER_RUNTIME`.
+- `bioflow doctor` recognises Podman as a Docker alternative — the
+  `docker_cli` / `docker_daemon` checks fall back to `podman` and report
+  which runtime they found.
+- Tests: +10 (`tests/unit/test_gpu_podman.py`).  Backend `run()` gains a
+  `gpu` kwarg (the `ContainerBackend` protocol + MockBackend updated).
+
+### Added — reference-DB catalog expansion + refgenie manifest
+- `bioflow/core/db.py` catalog gains the references real recipes need:
+  GATK known-sites `dbsnp_grch38` + `mills_indels_grch38` (BQSR/VQSR),
+  `encode_blacklist_grch38` (ChIP/ATAC peak filtering), and
+  `gencode_grch38` (STAR/Salmon/featureCounts annotation).
+- Catalog entries now carry `genome` + `asset` tags, and a new
+  `refgenie_manifest()` / `bioflow db manifest` emits a
+  [refgenie](https://refgenie.databio.org/)-compatible JSON mapping
+  `<genome>/<asset>` → catalogued DB, so labs already standardised on
+  refgenie can see which existing assets satisfy a bioflow requirement.
+- Tests: +5 (`tests/unit/test_db.py`).
+
+### Added — rnaseq_deg depth: GO enrichment + MultiQC
+- `rnaseq_deg` extended from 4 → 6 stages:
+  - **`enrich_go`** — GO enrichment on the significant DEGs via gseapy's
+    Enrichr query.  Symbol-based, so no organism-specific OrgDb package
+    is needed; an awk numeric-regex guard on the `padj` column avoids the
+    classic "NA-treated-as-0" false positive.
+  - **`multiqc_report`** — aggregates every per-sample fastp + Salmon
+    report into a single MultiQC HTML.
+- DAG-shape test updated; recipe still runs end-to-end under MockBackend.
+
+### Added — `joint_genotyping` recipe (GATK cohort best practice)
+- New 7-stage recipe (`bioflow/recipes/variant_calling/joint_genotyping.py`)
+  implementing the canonical GATK **joint-genotyping** workflow for
+  cohorts, where `germline_variants` only does single-sample direct
+  calling:
+  - **per sample (fan-out)**: fastp → BWA-MEM → MarkDuplicates →
+    HaplotypeCaller `-ERC GVCF`
+  - **cohort (converge)**: CombineGVCFs → GenotypeGVCFs →
+    best-practice hard filtering (separate SNP / INDEL filters) → SnpEff
+- Takes a `sample_id,fastq_r1,fastq_r2` sample sheet and uses `.starmap`
+  to run the per-sample stages in parallel before converging on the
+  joint steps — the production pattern reviewers expect for population
+  and family studies, and a worked example of bioflow's fan-out.
+- Recipe count 19 → 20 (12 per-pipeline).  Tests: +3 (registration, DAG
+  shape, MockBackend e2e).
+
+### Added — run provenance (RO-Crate + PROV-style JSON)
+- `bioflow/core/provenance.py` (new): every recipe run records, per
+  stage, the container **image + content digest**, the exact
+  **command**, every **input file's SHA-256 + size**, **start/end**
+  timestamps, exit code, and the bioflow version.
+- At the end of a run the workspace gains two self-describing files:
+  - `provenance.json` — flat, human-readable run record
+  - `ro-crate-metadata.json` — an [RO-Crate 1.1](https://www.researchobject.org/ro-crate/)
+    research object (the de-facto packaging standard for computational
+    workflow runs), so the output directory is consumable by reviewers
+    and downstream tools directly.
+- Wired into `bioflow recipe run` (on by default; `--no-provenance` to
+  skip).  Opt-in and **zero-cost when off** — the SDK hot path pays
+  nothing unless a recorder is installed, and provenance errors degrade
+  to warnings rather than aborting the science.
+- New `bioflow provenance show <workspace>` command (+ `--json`) renders
+  the recorded run: per-stage image, pinned digest, exit status, and
+  input hashes.  Builds directly on the digest-pinning work — pinned
+  tools show their `sha256:…` in the provenance.
+- Tests: +14 (`tests/unit/test_provenance.py`); verified end-to-end
+  against real Docker (digest resolved from the local image, RO-Crate
+  validates structurally).
+
+### Fixed — registry freshness (stale BioContainer tags)
+- **Discovery**: an audit during digest-pinning found that ~half the
+  registry's `quay.io/biocontainers/*` image tags had 404'd.  Quay
+  rotates each package's `--<buildhash>_<n>` build suffix and garbage-
+  collects the old ones, so dozens of recipes (chip_seq, atac_seq,
+  eukaryote_assembly, metagenome_assembly, rnaseq_deg's Salmon stage,
+  …) would have failed at run time with "image not found" — unrelated
+  to the user's data.
+- `scripts/refresh_tags.py` (new): audits every Quay BioContainer
+  reference, and with `--apply` rewrites any dead tag to the newest
+  *same-version* build (never changing the upstream software version).
+  Non-Quay images and versions that have left Quay entirely are
+  reported for manual review.
+- Applied: **34 registry tool YAMLs** + **7 recipe-hardcoded images**
+  (bowtie2, bracken, flye, macs3, medaka, metabat2, tobias) re-pointed
+  to live tags.  Salmon's `1.10.3--hb950928_0` → `1.10.3--h45fbf2d_5`
+  fixed separately (it broke the rnaseq_deg quant stage).
+- Verified: the bumped images pull + run (e.g. `bowtie2 2.5.4`), and
+  the nightly smoke matrix is green.
+
+### Added — full digest pinning (registry now 100% content-addressed)
+- Digest coverage raised from 5/110 → **107/107 active tools** in two
+  passes.  The second pass resolved the 17 hold-outs:
+  - **Version bumps** to the newest BioContainer of the same tool where
+    the pinned version had left Quay: DESeq2 1.44→1.50.2, edgeR
+    4.2→4.8.2, limma 3.60→3.66, clusterProfiler 4.12→4.18.4, topGO
+    2.56→2.62, HOMER 4.11.1→5.1, Scanpy 1.10.1→1.7.2 (1.10 was never on
+    Quay biocontainers), Comet 2024020→2026011, Percolator 3.06.1→3.7.1,
+    InterProScan 5.67→5.59.
+  - **Image-source switches**: methylKit and monocle3 moved off the
+    multi-GB `bioconductor/bioconductor_full:RELEASE_3_18` (gone) to the
+    dedicated `bioconductor-methylkit` / `r-monocle3` BioContainers;
+    Cell Ranger tag `7.2.0`→`v7.2.0`; Seurat `5.0.1`→`5.0.0`.
+  - **Deprecations**: MaxQuant joins MSFragger + FragPipe as
+    `deprecated: true` — proprietary tools whose images are gone and
+    which the `proteomics_dda` recipe does not use (it runs the
+    open-source msconvert → Comet → Percolator stack).  The audit now
+    skips deprecated tools.
+- **CI `digest-audit` is now blocking** (was advisory): every active
+  tool must carry an `image_digest`, so the registry can never silently
+  rot again.
+- `scripts/refresh_tags.py` also reports `version_gone` and non-Quay
+  images for these manual cases.
+
+### Added — Bioconda recipe (prep)
+- `conda-recipe/meta.yaml`: noarch-python Bioconda recipe (only
+  bioflow's pure-Python stack is a conda dep; tools run as Docker
+  containers).  Submission walkthrough in `docs/MAINTAINER.md` Part 7.
+  Gated on the real-PyPI publish (the recipe sources the PyPI sdist).
+
+### Changed — CI
+- All workflows opt into the Node 24 runtime
+  (`FORCE_JAVASCRIPT_ACTIONS_TO_NODE24`) ahead of the 2026-06-16 forced
+  switch, silencing the Node 20 deprecation warnings.
+
+### Fixed — nightly smoke
+- `rnaseq_deg.qc_one` smoke assertion matched the stage's real output
+  names (`<sample_id>_R1.clean.fq.gz`), fixing a false CI failure.
+
+---
+
 ## [0.2.0] — 2026-06-05
 
 First PyPI release.  Three months of 0.1.x work consolidated into a