ehsanestaji · ehsanestaji · Jul 3, 2026 · Jul 3, 2026
diff --git a/docs/adoption-plan.md b/docs/adoption-plan.md
@@ -71,13 +71,15 @@ 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.
+pinned to the v0.5.0 Bioconda package and BioContainers image, documented as
+starters rather than official upstream submissions, and validated in dedicated
+upstream-style checkouts on 2026-07-03.
 
 Next work:
 
-- complete nf-core lint and test harness requirements
-- complete Snakemake wrapper metadata, pin, and upstream test requirements
+- prepare external PR branches for nf-core/modules and snakemake-wrappers
+- repeat nf-core lint/test and Snakemake formatting/lint/pytest immediately
+  before opening upstream PRs
 - preserve the collect-then-gate pattern so JSON, TSV, HTML, and MultiQC
   evidence survives blocking FASTA results
 - keep `examples/workflows/check_fastaguard_gate.py` aligned with the JSON gate

diff --git a/docs/superpowers/plans/2026-07-03-upstream-workflow-prep.md b/docs/superpowers/plans/2026-07-03-upstream-workflow-prep.md
@@ -38,7 +38,7 @@
   - Read FastaGuard JSON and return 0 for PASS, 1 for WARN, 2 for FAIL, 3 for malformed tool input.
 - Create: `tests/python/test_workflow_gate_helper.py`
   - Verify the gate helper exits correctly from small JSON fixtures.
-- Create: `examples/snakemake/wrapper/environment.linux-64.pin.yaml`
+- Create: `examples/snakemake/wrapper/environment.linux-64.pin.txt`
   - Local starter pin file for upstream wrapper preparation.
 - Create: `examples/snakemake/wrapper/test/Snakefile`
   - Official-wrapper-style local test Snakefile.
@@ -90,7 +90,7 @@ Append these methods inside `AdoptionAssetsTest` before `test_benchmarking_docs_
         readme = (wrapper / "README.md").read_text()
         test_snakefile = (wrapper / "test" / "Snakefile").read_text()
         test_py = (wrapper / "test" / "test_wrappers.py").read_text()
-        pin = (wrapper / "environment.linux-64.pin.yaml").read_text()
+        pin = (wrapper / "environment.linux-64.pin.txt").read_text()
 
         self.assertIn("safe local order", readme)
         self.assertIn("fastaguard=0.5.0", pin)
@@ -454,15 +454,15 @@ Expected: PASS.
 ### Task 4: Harden Snakemake Wrapper Starter
 
 **Files:**
-- Create: `examples/snakemake/wrapper/environment.linux-64.pin.yaml`
+- Create: `examples/snakemake/wrapper/environment.linux-64.pin.txt`
 - Create: `examples/snakemake/wrapper/test/Snakefile`
 - Create: `examples/snakemake/wrapper/test/test_wrappers.py`
 - Create data fixtures under `examples/snakemake/wrapper/test/data/`
 - Modify: `examples/snakemake/wrapper/README.md`
 
 - [ ] **Step 1: Add starter pin file**
 
-Create `examples/snakemake/wrapper/environment.linux-64.pin.yaml`:
+Create `examples/snakemake/wrapper/environment.linux-64.pin.txt`:
 
 ```yaml
 channels:
@@ -490,7 +490,7 @@ rule fastaguard_pass:
         gate="pipeline",
         extra=""
     wrapper:
-        "file:../wrapper/fastaguard"
+        "master/bio/fastaguard"
 
 
 rule fastaguard_warn:
@@ -506,7 +506,7 @@ rule fastaguard_warn:
         gate="none",
         extra=""
     wrapper:
-        "file:../wrapper/fastaguard"
+        "master/bio/fastaguard"
 
 
 rule fastaguard_fail:
@@ -522,7 +522,7 @@ rule fastaguard_fail:
         gate="none",
         extra=""
     wrapper:
-        "file:../wrapper/fastaguard"
+        "master/bio/fastaguard"
 
 
 rule fastaguard_invalid:
@@ -538,7 +538,7 @@ rule fastaguard_invalid:
         gate="none",
         extra=""
     wrapper:
-        "file:../wrapper/fastaguard"
+        "master/bio/fastaguard"
 ```
 
 - [ ] **Step 3: Add copy-pasteable test runner snippet**
@@ -609,7 +609,7 @@ Safe local order before upstream submission:
 1. Run repository Python tests that inspect this wrapper layout.
 2. Install Snakemake in a workflow test environment.
 3. Run `snakemake -s test/Snakefile --cores 1 --use-conda`.
-4. Generate a real upstream `environment.linux-64.pin.yaml` if the upstream
+4. Generate a real upstream `environment.linux-64.pin.txt` if the upstream
    wrapper repository requires a solver-produced pin file.
 5. Adapt `test/test_wrappers.py` into the upstream wrapper repository test
    harness.
@@ -743,7 +743,7 @@ Run:
 
 ```bash
 git status --short
-git add tests/python/test_adoption_assets.py tests/python/test_workflow_gate_helper.py docs/workflow-readiness.md docs/adoption-plan.md examples/nf-core/README.md examples/nf-core/modules/local/fastaguard/main.nf examples/nf-core/modules/local/fastaguard/meta.yml examples/nf-core/modules/local/fastaguard/tests examples/workflows/check_fastaguard_gate.py examples/snakemake/wrapper/README.md examples/snakemake/wrapper/environment.linux-64.pin.yaml examples/snakemake/wrapper/test docs/superpowers/plans/2026-07-03-upstream-workflow-prep.md
+git add tests/python/test_adoption_assets.py tests/python/test_workflow_gate_helper.py docs/workflow-readiness.md docs/adoption-plan.md examples/nf-core/README.md examples/nf-core/modules/local/fastaguard/main.nf examples/nf-core/modules/local/fastaguard/meta.yml examples/nf-core/modules/local/fastaguard/tests examples/workflows/check_fastaguard_gate.py examples/snakemake/wrapper/README.md examples/snakemake/wrapper/environment.linux-64.pin.txt examples/snakemake/wrapper/test docs/superpowers/plans/2026-07-03-upstream-workflow-prep.md
 git commit -m "docs: prepare upstream workflow starters"
 git push -u origin feature/upstream-workflow-prep
 ```

diff --git a/docs/workflow-readiness.md b/docs/workflow-readiness.md
@@ -21,6 +21,17 @@ The repository includes local starters for:
 These are workflow adoption starters. They are not yet an upstream nf-core module.
 They are not yet an official Snakemake wrapper.
 
+External upstream-style validation was run on 2026-07-03 in dedicated checkouts:
+
+- `nf-core modules lint fastaguard`: 47 tests passed, 0 warnings, 0 failures.
+- `nf-core modules test fastaguard --profile conda --once --no-prompts`: all
+  nf-test cases passed against Bioconda v0.5.0.
+- Snakemake wrapper formatting: `black --check` and `snakefmt --check` passed.
+- Snakemake wrapper lint: `snakemake --lint --snakefile test/Snakefile` passed.
+- Snakemake wrapper pytest: `test_wrappers.py::test_fastaguard` passed with
+  PASS, WARN, FAIL, and invalid FASTA fixtures plus captured `exit_code`
+  outputs.
+
 ## Safe Order
 
 1. Run local repository tests first.
@@ -60,18 +71,20 @@ matters. The important contract fields are:
 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
+- outputs: HTML, JSON, TSV, MultiQC custom-content JSON, captured exit code,
+  and versions metadata
 - runtime: `bioconda::fastaguard=0.5.0`
 - container: `quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0`
 - starter nf-test fixture layout for PASS, WARN, FAIL, and invalid FASTA cases
 - topic-aware `versions.yml` output for current nf-core version collection
 
-Before an upstream nf-core module submission, complete this checklist:
+Before an upstream nf-core module submission, repeat this checklist in a fresh
+upstream checkout:
 
 - regenerate or validate the module against the current `nf-core/tools`
   template
 - run `nf-core modules lint fastaguard`
-- run `nf-core modules test fastaguard`
+- run `nf-core modules test fastaguard --profile conda --once --no-prompts`
 - adapt the local nf-test starter into the upstream repository layout
 - assert that `.fastaguard.json`, `.fastaguard.tsv`, `.fastaguard.html`,
   `.fastaguard_mqc.json`, and version outputs are produced
@@ -90,14 +103,15 @@ The local wrapper starter already provides:
 - `wrapper.py`
 - `environment.yaml`
 - `meta.yaml`
-- `environment.linux-64.pin.yaml` as a local starter pin file
+- `environment.linux-64.pin.txt` as a local starter pin file
 - a copy-pasteable `Snakefile`
 - a `test/Snakefile` starter with PASS, WARN, FAIL, and invalid FASTA fixtures
-- outputs for HTML, JSON, TSV, and MultiQC custom-content JSON
+- outputs for HTML, JSON, TSV, MultiQC custom-content JSON, and captured exit
+  code
 
 Before an official Snakemake wrapper submission, complete this checklist:
 
-- regenerate `environment.linux-64.pin.yaml` from the wrapper environment if
+- regenerate `environment.linux-64.pin.txt` from the wrapper environment if
   the upstream repository requires a solver-produced pin file
 - adapt the local `test/Snakefile` and tiny FASTA fixtures
 - update `test_wrappers.py` so wrapper tests run in the upstream repository

diff --git a/examples/nf-core/modules/local/fastaguard/main.nf b/examples/nf-core/modules/local/fastaguard/main.nf
@@ -1,7 +1,11 @@
 process FASTAGUARD {
     tag "$meta.id"
     label 'process_low'
-    container 'quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0'
+
+    conda "${moduleDir}/environment.yml"
+    container "${ workflow.containerEngine in ['singularity', 'apptainer'] && !task.ext.singularity_pull_docker_container ?
+        'https://depot.galaxyproject.org/singularity/fastaguard:0.5.0--hfa8f182_0':
+        'quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0' }"
 
     input:
     tuple val(meta), path(fasta)
@@ -11,22 +15,30 @@ process FASTAGUARD {
     tuple val(meta), path("*.fastaguard.json"), emit: json
     tuple val(meta), path("*.fastaguard.tsv"), emit: tsv
     tuple val(meta), path("*.fastaguard_mqc.json"), emit: mqc
-    path "versions.yml", emit: versions, topic: versions
+    tuple val(meta), path("*.fastaguard.exit_code"), emit: exit_code
+    tuple val("${task.process}"), val('fastaguard'), eval('fastaguard --version | cut -d " " -f 2'), emit: versions_fastaguard, topic: versions
+
+    when:
+    task.ext.when == null || task.ext.when
 
     script:
     def prefix = task.ext.prefix ?: meta.id
+    def args = task.ext.args ?: '--profile assembly --gate pipeline'
     """
+    set +e
     fastaguard ${fasta} \
-      --profile assembly \
-      --gate pipeline \
+      ${args} \
       --out ${prefix}.fastaguard.html \
       --json ${prefix}.fastaguard.json \
       --tsv ${prefix}.fastaguard.tsv \
       --multiqc ${prefix}.fastaguard_mqc.json
+    status=\$?
+    set -e
+
+    printf "%s\\n" "\${status}" > ${prefix}.fastaguard.exit_code
 
-    cat <<-END_VERSIONS > versions.yml
-    "${task.process}":
-        fastaguard: \$(fastaguard --version | awk '{print \$2}')
-    END_VERSIONS
+    if [ "\${status}" -eq 3 ]; then
+      exit "\${status}"
+    fi
     """
 }
diff --git a/examples/nf-core/modules/local/fastaguard/meta.yml b/examples/nf-core/modules/local/fastaguard/meta.yml
@@ -1,52 +1,108 @@
-name: fastaguard
+name: "fastaguard"
 description: FASTA preflight QC for assembly pipelines
 keywords:
   - fasta
   - assembly
   - qc
 tools:
-  - fastaguard:
+  - "fastaguard":
       description: FASTA preflight QC for assembly pipelines
-      licence: ["MIT"]
+      homepage: "https://github.com/ehsanestaji/FastaGuard"
+      documentation: "https://github.com/ehsanestaji/FastaGuard"
+      tool_dev_url: "https://github.com/ehsanestaji/FastaGuard"
+      licence:
+        - "MIT"
+      identifier: ""
 input:
-  - meta:
-      type: map
-      description: Sample metadata map containing at least an id key.
-  - fasta:
-      type: file
-      description: Assembly FASTA file.
-      pattern: "*.{fa,fasta,fa.gz,fasta.gz}"
+  - - meta:
+        type: map
+        description: |
+          Groovy Map containing sample information
+          e.g. [ id:'sample' ]
+    - fasta:
+        type: file
+        description: Assembly FASTA file
+        pattern: "*.{fa,fasta,fa.gz,fasta.gz}"
+        ontologies: []
 output:
-  - html:
-      type: file
-      description: FastaGuard HTML report.
-      pattern: "*.fastaguard.html"
-  - json:
-      type: file
-      description: FastaGuard JSON report.
-      pattern: "*.fastaguard.json"
-  - tsv:
-      type: file
-      description: FastaGuard TSV summary.
-      pattern: "*.fastaguard.tsv"
-  - mqc:
-      type: file
-      description: MultiQC custom-content JSON.
-      pattern: "*.fastaguard_mqc.json"
-  - versions:
-      type: file
-      description: Software versions file.
-      pattern: "versions.yml"
+  html:
+    - - meta:
+          type: map
+          description: |
+            Groovy Map containing sample information
+            e.g. [ id:'sample' ]
+      - "*.fastaguard.html":
+          type: file
+          description: FastaGuard HTML report
+          pattern: "*.fastaguard.html"
+          ontologies: []
+  json:
+    - - meta:
+          type: map
+          description: |
+            Groovy Map containing sample information
+            e.g. [ id:'sample' ]
+      - "*.fastaguard.json":
+          type: file
+          description: FastaGuard JSON report
+          pattern: "*.fastaguard.json"
+          ontologies:
+            - edam: http://edamontology.org/format_3464
+  tsv:
+    - - meta:
+          type: map
+          description: |
+            Groovy Map containing sample information
+            e.g. [ id:'sample' ]
+      - "*.fastaguard.tsv":
+          type: file
+          description: FastaGuard TSV summary
+          pattern: "*.fastaguard.tsv"
+          ontologies:
+            - edam: http://edamontology.org/format_3475
+  mqc:
+    - - meta:
+          type: map
+          description: |
+            Groovy Map containing sample information
+            e.g. [ id:'sample' ]
+      - "*.fastaguard_mqc.json":
+          type: file
+          description: MultiQC custom-content JSON
+          pattern: "*.fastaguard_mqc.json"
+          ontologies:
+            - edam: http://edamontology.org/format_3464
+  exit_code:
+    - - meta:
+          type: map
+          description: |
+            Groovy Map containing sample information
+            e.g. [ id:'sample' ]
+      - "*.fastaguard.exit_code":
+          type: file
+          description: FastaGuard CLI exit code for collect-then-gate workflows
+          pattern: "*.fastaguard.exit_code"
+          ontologies: []
+  versions_fastaguard:
+    - - ${task.process}:
+          type: string
+          description: The process the versions were collected from
+      - fastaguard:
+          type: string
+          description: The tool name
+      - fastaguard --version | cut -d " " -f 2:
+          type: eval
+          description: The expression to obtain the version of the tool
 topics:
   versions:
-    - - process:
-          type: string
-          description: The process the versions were collected from.
-      - tool:
+    - - ${task.process}:
           type: string
-          description: The tool name.
-      - version:
+          description: The process the versions were collected from
+      - fastaguard:
           type: string
-          description: The version reported by the tool.
+          description: The tool name
+      - fastaguard --version | cut -d " " -f 2:
+          type: eval
+          description: The expression to obtain the version of the tool
 authors:
-  - FastaGuard contributors
+  - "FastaGuard contributors"
diff --git a/examples/nf-core/modules/local/fastaguard/tests/data/pass.fa b/examples/nf-core/modules/local/fastaguard/tests/data/pass.fa
@@ -1,4 +1,2 @@
->contig1
-ACGTACGTACGTACGT
->contig2
-GCGCGCATATAT
+>clean
+ACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGT
diff --git a/examples/nf-core/modules/local/fastaguard/tests/data/warn.fa b/examples/nf-core/modules/local/fastaguard/tests/data/warn.fa
@@ -1,4 +1,4 @@
->tiny1
+>long
+ACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGT
+>tiny
 ACGT
->tiny2
-NNNNNNNN