Define workflow readiness path

README.md

@@ -316,6 +316,7 @@ FastaGuard catches FASTA-level assembly problems before expensive assembly QC.
 - [Output contract](docs/output-contract.md)
 - [Tool landscape](docs/tool-landscape.md)
 - [Adoption plan](docs/adoption-plan.md)
+- [Workflow readiness](docs/workflow-readiness.md)
 - [LLM and tooling vision](docs/llm-tooling-vision.md)
 - [Benchmarking](docs/benchmarking.md)
 - [v0.2 evidence pack](docs/evidence/fastaguard-v0.2-evidence.md)

docs/adoption-plan.md

@@ -8,7 +8,7 @@ adding many new biological heuristics.
 Priority:
 
 ```text
-Bioconda published -> BioContainers available -> MultiQC plugin -> public benchmarks -> upstream workflow examples
+Bioconda published -> BioContainers available -> MultiQC plugin -> public benchmarks -> upstream workflow readiness
 ```
 
 ## Phase 1: Package
@@ -65,7 +65,41 @@ Goal: show why FastaGuard is worth adding before expensive tools.
 
 Done when the README can show real examples rather than only promises.
 
-## Phase 4: Expand
+## Phase 4: Workflow Readiness
+
+Goal: make local workflow starters credible enough to become upstream
+submissions.
+
+Status: local nf-core-style and Snakemake wrapper-style starters are present,
+pinned to the v0.5.0 Bioconda package and BioContainers image, and documented
+as starters rather than official upstream submissions.
+
+Next work:
+
+- complete nf-core lint and test harness requirements
+- complete Snakemake wrapper metadata, pin, and upstream test requirements
+- preserve the collect-then-gate pattern so JSON, TSV, HTML, and MultiQC
+  evidence survives blocking FASTA results
+- keep the workflow examples focused on stable FastaGuard contracts instead of
+  broad biological interpretation
+
+Detailed checklist: `docs/workflow-readiness.md`.
+
+## Phase 5: Upstream workflow readiness
+
+Goal: submit the starter assets upstream once the package, container, examples,
+and tests are aligned with current community expectations.
+
+Done when:
+
+```text
+nf-core module PR ready + Snakemake wrapper PR ready + local evidence-preserving examples verified
+```
+
+This phase should not claim official upstream status until those PRs are
+accepted.
+
+## Phase 6: Expand
 
 Goal: add profiles once the assembly preflight contract is trusted.
 

docs/workflow-readiness.md

@@ -0,0 +1,120 @@
+# Workflow Readiness
+
+## Current State
+
+FastaGuard is ready for local workflow use through the published v0.5.0
+Bioconda package and BioContainers image:
+
+```bash
+mamba install -c conda-forge -c bioconda fastaguard=0.5.0
+docker pull quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0
+```
+
+The repository includes local starters for:
+
+- nf-core-style Nextflow modules in `examples/nf-core/`
+- Snakemake wrapper-style usage in `examples/snakemake/wrapper/`
+- MultiQC custom-content aggregation through `fastaguard_mqc.json`
+
+These are workflow adoption starters. They are not yet an upstream nf-core module.
+They are not yet an official Snakemake wrapper.
+
+## Integration Pattern
+
+FastaGuard should run before QUAST, BUSCO, BlobToolKit, CheckM, annotation, or
+official submission validators. The default workflow pattern is:
+
+```text
+collect FASTA-level evidence -> apply stop/go policy -> route downstream tools
+```
+
+For local fail-fast runs, `--gate pipeline` and `--gate submission` write JSON,
+TSV, HTML, and MultiQC-compatible evidence before returning a blocking exit
+code. Some workflow engines remove failed-job outputs by default, so production
+integrations should use a collect-then-gate pattern when evidence preservation
+matters. The important contract fields are:
+
+- `verdict.status`
+- `gate.mode`
+- `gate.status`
+- `gate.blocking_findings`
+- `readiness.categories`
+- `provenance.input_sha256`
+
+## nf-core Readiness
+
+The local module already carries the expected interface shape:
+
+- input channel: `tuple val(meta), path(fasta)`
+- outputs: HTML, JSON, TSV, MultiQC custom-content JSON, and versions metadata
+- runtime: `bioconda::fastaguard=0.5.0`
+- container: `quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0`
+
+Before an upstream nf-core module submission, complete this checklist:
+
+- regenerate or validate the module against the current `nf-core/tools`
+  template
+- run `nf-core modules lint fastaguard`
+- run `nf-core modules test fastaguard`
+- add nf-test cases for PASS, WARN, FAIL, and invalid FASTA inputs
+- assert that `.fastaguard.json`, `.fastaguard.tsv`, `.fastaguard.html`,
+  `.fastaguard_mqc.json`, and version outputs are produced
+- align `meta.yml` with current nf-core channel metadata expectations
+- check current nf-core topic channels guidance for version outputs
+- document that FastaGuard remains a FASTA preflight gate, not a replacement
+  for downstream interpretive QC
+
+The upstream submission should keep the module boring: database-free, pinned to
+Bioconda/BioContainers, and focused on stable machine-readable outputs.
+
+## Snakemake Readiness
+
+The local wrapper starter already provides:
+
+- `wrapper.py`
+- `environment.yaml`
+- `meta.yaml`
+- a copy-pasteable `Snakefile`
+- outputs for HTML, JSON, TSV, and MultiQC custom-content JSON
+
+Before an official Snakemake wrapper submission, complete this checklist:
+
+- generate `environment.linux-64.pin.yaml` from the wrapper environment
+- add `test/Snakefile` with tiny FASTA fixtures
+- update `test_wrappers.py` so wrapper tests run in the upstream repository
+- test PASS, WARN, FAIL, and invalid FASTA behavior
+- ensure the wrapper can handle arbitrary input and output paths
+- preserve evidence on blocking FASTA results, either through workflow-specific
+  output handling or a collect-then-gate wrapper pattern
+
+## Submission Gate Usage
+
+For repository-preflight workflows, use:
+
+```bash
+fastaguard sample.fa \
+  --profile assembly \
+  --gate submission \
+  --submission-target ncbi \
+  --json fastaguard.json \
+  --tsv fastaguard.tsv \
+  --out fastaguard_report.html \
+  --multiqc fastaguard_mqc.json
+```
+
+This is FASTA-level readiness only. It can identify identifier hazards,
+duplicate first-token IDs, high ambiguity, gap-like N runs, and tiny-record
+advisories. It does not guarantee repository acceptance and does not replace
+NCBI, ENA, DDBJ, NCBI FCS, annotation validation, QUAST, BUSCO, BlobToolKit, or
+CheckM.
+
+## References Checked
+
+Current upstream expectations were checked on 2026-07-03 against:
+
+- nf-core modules repository and `nf-core modules lint` workflow:
+  https://github.com/nf-core/modules
+- nf-core topic channels migration guidance:
+  https://nf-co.re/docs/tutorials/migrate_to_topics/update_modules
+- Snakemake wrappers contributing guidance:
+  https://snakemake-wrappers.readthedocs.io/en/stable/contributing.html

examples/nf-core/README.md

@@ -2,6 +2,9 @@
 
 This directory is a starter for a local nf-core-style FastaGuard module. It is not yet an upstream nf-core module.
 
+See `../../docs/workflow-readiness.md` for the current upstream readiness
+checklist before submitting this starter to nf-core.
+
 Expected input channel:
 
 ```nextflow

examples/nf-core/modules/local/fastaguard/environment.yml

@@ -0,0 +1,5 @@
+channels:
+  - conda-forge
+  - bioconda
+dependencies:
+  - bioconda::fastaguard=0.5.0

examples/snakemake/wrapper/README.md

@@ -2,6 +2,9 @@
 
 This is a local wrapper-style starter for FastaGuard. It assumes `fastaguard` is available on `PATH`.
 
+See `../../../docs/workflow-readiness.md` for the current upstream readiness
+checklist before submitting this starter as an official Snakemake wrapper.
+
 Published Bioconda provides v0.5.0:
 
 ```bash

examples/snakemake/wrapper/meta.yaml

@@ -0,0 +1,19 @@
+name: fastaguard
+description: FASTA preflight QC for assembly and submission-readiness workflows.
+url: https://github.com/ehsanestaji/FastaGuard
+authors:
+  - FastaGuard contributors
+input:
+  fasta: Assembly FASTA file to validate before downstream QC.
+output:
+  html: Human-readable FastaGuard report.
+  json: Machine-readable FastaGuard report.
+  tsv: Tabular FastaGuard summary.
+  multiqc: MultiQC custom-content JSON.
+params:
+  profile: FastaGuard profile, normally assembly.
+  gate: FastaGuard gate mode, normally pipeline or submission.
+  extra: Additional command-line arguments passed to FastaGuard.
+notes: >
+  FastaGuard is a FASTA preflight layer. It should run before downstream
+  interpretive QC tools and official validators, not replace them.

tests/python/test_adoption_assets.py

@@ -533,6 +533,46 @@ def test_workflow_docs_reference_bioconda_and_container_status(self):
             snakemake_readme,
         )
 
+    def test_workflow_readiness_plan_defines_upstream_submission_path(self):
+        readme = (ROOT / "README.md").read_text()
+        adoption = (ROOT / "docs" / "adoption-plan.md").read_text()
+        readiness = (ROOT / "docs" / "workflow-readiness.md").read_text()
+        nfcore_readme = (ROOT / "examples" / "nf-core" / "README.md").read_text()
+        nfcore_environment = (
+            ROOT
+            / "examples"
+            / "nf-core"
+            / "modules"
+            / "local"
+            / "fastaguard"
+            / "environment.yml"
+        ).read_text()
+        snakemake_readme = (
+            ROOT / "examples" / "snakemake" / "wrapper" / "README.md"
+        ).read_text()
+        snakemake_meta = (
+            ROOT / "examples" / "snakemake" / "wrapper" / "meta.yaml"
+        ).read_text()
+
+        self.assertIn("[Workflow readiness](docs/workflow-readiness.md)", readme)
+        self.assertIn("Phase 5: Upstream workflow readiness", adoption)
+        self.assertIn("not yet an upstream nf-core module", readiness)
+        self.assertIn("not yet an official Snakemake wrapper", readiness)
+        self.assertIn("collect-then-gate", readiness)
+        self.assertIn("nf-core modules lint", readiness)
+        self.assertIn("nf-core modules test", readiness)
+        self.assertIn("topic channels", readiness)
+        self.assertIn("environment.linux-64.pin.yaml", readiness)
+        self.assertIn("test_wrappers.py", readiness)
+        self.assertIn("--gate submission", readiness)
+        self.assertIn("quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0", readiness)
+        self.assertIn("docs/workflow-readiness.md", nfcore_readme)
+        self.assertIn("docs/workflow-readiness.md", snakemake_readme)
+        self.assertIn("fastaguard=0.5.0", nfcore_environment)
+        self.assertIn("name: fastaguard", snakemake_meta)
+        self.assertIn("description:", snakemake_meta)
+        self.assertIn("output:", snakemake_meta)
+
     def test_benchmarking_docs_include_v0_2_evidence_topics(self):
         text = (ROOT / "docs" / "benchmarking.md").read_text()