FastaGuard v1.0.0

FastaGuard v1.0.0 — Reference Contract Gate

Release

FastaGuard v1.0.0 introduces the Reference Contract Gate while preserving the
established assembly, compare, report, and workflow interfaces.

Reference compatibility

fastaguard reference compares explicitly supplied reference declarations with
one canonical FASTA. It supports FAI files, SAM sequence dictionaries, BAM and
CRAM headers, VCF and BCF contig declarations, and GFF3 sequence declarations.
It does not discover sidecar files implicitly or inspect alignment and variant
records.

The command provides strict, coordinate, and advisory policies; reports stable
findings in JSON, TSV, HTML, and MultiQC-compatible outputs; and can write a
portable lockfile for the reference identity and declared artefacts.

Report contract

Assembly reports retain schema version 0.7.0 and now include the additive
report_type: "assembly" discriminator. Compare reports retain
report_type: "compare" and schema version 0.7.0. Reference reports use
report_type: "reference" and Reference Contract schema version 1.0.0.
The nf-core and Snakemake integrations keep their existing workflow interfaces.

Measured workflow value

On a 4.42-million-pair E. coli dataset, FastaGuard detected a one-base
reference-index mismatch before mapping, avoiding a 45-second mapping-and-
sorting task in both Snakemake and Nextflow. The measurement is scoped to the
documented controlled baseline and does not claim a universal saving. See the
workflow savings benchmark for the method
and results.

Downstream availability

The GitHub release includes the executable, README, licence, JSON Schema,
finding catalogue, and SHA-256 checksums. Bioconda and BioContainers remain at
v0.7.0 until the downstream recipe update is merged and published. The existing
nf-core module and Snakemake wrapper continue to use that published package in
the meantime.

The release is validated with deterministic Rust and Python tests, schema and
archive checks, and local workflow smoke tests.

FastaGuard v0.7.0

FastaGuard v0.7.0

FastaGuard v0.7.0 strengthens assembly FASTA preflight for routine workflow use. It focuses on deterministic report publication, explicit policy scope, and machine-readable downstream decisions.

Highlights

• Safe four-file report bundles with no-clobber behavior by default and explicit --force replacement.
• Clear separation between report completion, QC verdicts, and downstream gate continuation.
• An opt-in NCBI genome FASTA preflight policy with documented boundaries; it does not replace official NCBI validation.
• Versioned schema and finding-catalog updates, parser robustness checks, and a validated MultiQC integration.

Archives

The archives contain the executable, README, license, and schema assets. Verify downloaded archives against SHA256SUMS before use.

Compatibility

FastaGuard remains an assembly-first, database-free FASTA preflight tool. Transcriptome, protein, and reference-panel profiles remain future work.

FastaGuard v0.6.0

FastaGuard v0.6.0

Workflow-Compatible Exit Contract

FastaGuard now separates command execution from FASTA quality decisions.
Successful report generation exits with code 0, including reports whose
verdict or gate status is WARN or FAIL. Argument parsing errors exit with
code 2, while configuration, input-access, and runtime errors exit with code
3.

QC decisions remain explicit in the report contract:

• verdict.status records the overall PASS/WARN/FAIL result.
• gate.status records the selected gate result.
• gate.blocking_findings lists findings that should stop downstream work.
• single-file TSV reports include input_path, verdict, and gate_status.
• compare TSV reports retain one row per input with its path and status fields.

This keeps JSON and TSV reports available to Nextflow, Snakemake, nf-core, and
other workflow engines. Pipelines can publish the evidence first and apply
their own stop/go policy downstream.

Migration

Workflows that previously interpreted process exit codes 1 and 2 as WARN
and FAIL should instead read gate.status or verdict.status from JSON or TSV.
The repository includes examples/workflows/check_fastaguard_gate.py for
workflows that need a separate enforcement step after reports are collected.

The JSON schema and finding catalog remain at version 0.5.0 because their
structures and finding semantics are unchanged in this release.

FastaGuard v0.5.0

FastaGuard v0.5.0

FastaGuard v0.5.0 is the Submission Readiness Gate release.

Highlights

• Adds --gate submission.
• Adds --submission-target generic|ncbi.
• Adds submission-readiness fields to JSON, TSV, HTML, MultiQC, and compare outputs.
• Promotes existing identifier, header, gap, ambiguity, and tiny-record findings into a clearer submission-readiness view.

Boundary

FastaGuard is a FASTA-level preflight tool. It does not replace NCBI, ENA,
DDBJ, NCBI FCS, QUAST, BUSCO, BlobToolKit, CheckM, annotation validation,
official validators, or official repository acceptance checks.

Passing --gate submission does not guarantee repository acceptance. It means
FastaGuard did not find the FASTA-level submission-readiness hazards represented
in its local, database-free contract.

FastaGuard v0.4.0

FastaGuard v0.4.0

GitHub release artifacts are built from the v0.4.0 tag.

Bioconda and BioContainers publication remain follow-up work after the GitHub
release is available.

Theme: Preflight Readiness + Compare Mode.

This release adds fastaguard compare, readiness categories, index-readiness
checks, submission-readiness advisories, and cohort triage outputs. FastaGuard
remains FASTA preflight QC and does not replace QUAST, BUSCO, BlobToolKit,
CheckM, official submission validators, or annotation workflows.

Highlights

• Adds compare mode for ranking and routing many FASTA files from one command.
• Adds readiness categories so humans and workflow engines can distinguish file,
  structure, alphabet, index, assembly, submission, and machine readiness.
• Adds index-readiness checks for identifier patterns that can break joins,
  indexes, annotations, or downstream sample tracking.
• Adds submission-readiness advisories for FASTA-level issues worth fixing
  before official validators or archive submission.
• Adds cohort JSON, TSV, HTML, and MultiQC-compatible outputs for starter
  multi-sample triage.

Boundary

FastaGuard v0.4.0 stays fast and database-free by default. Compare mode
aggregates FastaGuard's own FASTA-level evidence; it does not infer taxonomy,
prove biological completeness, replace assembly evaluation, or substitute for
official submission validation.

Publication Status

• Source/package metadata is 0.4.0.
• GitHub release binaries are produced from the v0.4.0 tag.
• Published Bioconda and BioContainers packages remain v0.3.0 until packaging
  follow-up is complete.

FastaGuard v0.3.0

FastaGuard v0.3.0

FastaGuard v0.3.0 is the Evidence And Assembly Gate release.

This release makes FastaGuard more useful as an early, machine-readable
assembly preflight gate before QUAST, BUSCO, BlobToolKit, CheckM, annotation,
or other expensive downstream QC.

Highlights

• Adds --gate pipeline, a conservative assembly gate preset for pipeline
  automation.
• Adds a machine-readable gate report object with mode, status, blocking
  findings, advisory findings, and the active failure policy.
• Adds provenance.input_sha256 so workflow engines and agents can tie a
  report back to the exact FASTA bytes that were checked.
• Updates JSON, TSV, HTML, and MultiQC-compatible outputs with the v0.3 report
  contract.
• Keeps stable finding IDs and structured actions as the source of truth for
  automation.
• Supports the v0.3 evidence workflow without requiring databases or external
  services for normal runs.

Install

Download the platform binary from this GitHub release, or build from source:

cargo install --git https://github.com/ehsanestaji/FastaGuard --tag v0.3.0
fastaguard --version

Bioconda and BioContainers updates should follow after the v0.3.0 source
archive and release assets are public.

Pipeline Gate

Use the assembly gate when FastaGuard should make a pipeline decision:

fastaguard sample.fa --gate pipeline \
  --out fastaguard_report.html \
  --json fastaguard.json \
  --tsv fastaguard.tsv \
  --multiqc fastaguard_mqc.json

--gate pipeline fails on conservative FASTA-level blockers such as invalid
FASTA structure, invalid characters, duplicate identifiers, and high global N
rate. Other findings can still be emitted as advisory evidence, so downstream
workflow logic can distinguish "stop and fix the FASTA" from "continue, but
route to deeper assembly QC."

Machine-Readable Outputs

The JSON report remains the source of truth. The v0.3.0 contract adds:

• gate.mode and gate.status for direct pipeline decisions.
• gate.blocking_findings and gate.advisory_findings for routing.
• gate.fail_on for the active failure policy after preset expansion.
• provenance.input_sha256 for input identity checks.
• Pipeline-friendly TSV fields that surface gate status and input checksum
  alongside the usual summary metrics.
• MultiQC-compatible fields that surface gate mode, gate status, and blocking
  finding IDs alongside the usual summary metrics.

Evidence Workflow

The evidence workflow for v0.3.0 is intended to show that the assembly gate,
report schema, provenance checksum, and committed examples are reproducible.
The workflow should use local FASTA metrics only; FastaGuard does not fetch
taxonomy databases or make biological completeness claims.

Known Limits

• FastaGuard remains a FASTA preflight tool, not a replacement for QUAST,
  BUSCO, BlobToolKit, CheckM, seqkit, MultiQC, or annotation workflows.
• --gate pipeline is intentionally conservative and database-free.
• Composition and outlier findings are triage signals, not contamination or
  taxonomic assignments.
• input_sha256 identifies the checked input bytes; it does not by itself
  prove sample identity, biological quality, or reference correctness.

FastaGuard v0.2.0

FastaGuard v0.2.0

FastaGuard v0.2.0 is the Assembly Trust + Pipeline Adoption release.

This release keeps FastaGuard focused on early FASTA preflight checks while
making the results easier to trust, route, and consume in real assembly
pipelines.

Highlights

• Adds explainable GC, length, and composite assembly outlier findings.
• Expands the JSON contract with richer provenance, taxonomy context, and
  routing hints for downstream tools.
• Hardens MultiQC plugin support for pipeline report aggregation.
• Adds Snakemake Bioconda environment starter material.
• Documents benchmark and evidence guidance for adoption decisions.

Install

Once v0.2.0 is published on Bioconda, install it with:

mamba install -c conda-forge -c bioconda fastaguard

Until then, Bioconda currently serves the latest published package, v0.1.1.
The v0.2.0 Bioconda recipe in this repository is staged and still needs the
published source archive SHA before submission.

Positioning

FastaGuard still runs before QUAST, BUSCO, BlobToolKit, annotation, and
submission. It does not replace downstream workflows for biological
completeness, assembly correctness, contamination exploration, or taxonomy
confirmation.

Use FastaGuard first to catch FASTA-level validity, structure, composition, and
reporting-contract problems before spending time on heavier assembly QC.

Known Limits

• FastaGuard remains assembly-focused.
• Composition outliers are triage signals, not contamination calls.
• External taxonomy, coverage, k-mer, and database-backed checks remain
  follow-up steps when a sample needs deeper biological interpretation.

FastaGuard v0.1.1

FastaGuard v0.1.1

FastaGuard v0.1.1 is a packaging metadata release for downstream adoption.

The CLI behavior remains assembly-focused and compatible with v0.1.0. The
important change is that the source tree now includes the metadata needed for a
clean Bioconda submission.

Highlights

• Adds an MIT LICENSE file to the source archive.
• Adds Bioconda recipe scaffolding under packaging/bioconda/.
• Adds a native MultiQC plugin starter under integrations/multiqc/.
• Adds adoption, tool landscape, and benchmark evidence planning docs.
• Updates CI and release workflows to Node 24-compatible GitHub action versions.

Install From Release Assets

Download the archive for your platform, unpack it, and place fastaguard on
PATH:

tar -xzf fastaguard-v0.1.1-x86_64-unknown-linux-gnu.tar.gz
./fastaguard-v0.1.1-x86_64-unknown-linux-gnu/fastaguard --help

Bioconda Note

This release is intended to be the first source archive suitable for Bioconda:
it contains the project license file and the stable v0.1 FASTA preflight
contract commands:

fastaguard --help
fastaguard --schema
fastaguard --finding-catalog

Known Limits

• v0.1.1 still supports the assembly profile only.
• FastaGuard does not estimate biological completeness, taxonomic
  contamination, or assembly correctness.
• Bioconda submission still requires the public source archive SHA256 to be
  recorded in the recipe.

FastaGuard v0.1.0

FastaGuard v0.1.0

FastaGuard v0.1.0 is the first assembly-focused FASTA preflight release.

The promise is deliberately narrow:

Before QUAST. Before BUSCO. Before BlobToolKit. Before annotation.
Run FastaGuard first.

Highlights

• Validates plain and gzipped assembly FASTA files.
• Detects malformed or empty records, duplicate IDs, duplicate sequences, invalid symbols, high-N content, tiny contigs, and long N gap runs.
• Reports N50, N90, L50, L90, GC%, AT%, N%, ambiguity rate, and core length statistics.
• Adds machine-readable JSON Schema, finding catalog, structured actions, bounded per-record evidence, provenance, and scope limits.
• Adds self-contained HTML reports with finding evidence, suggested actions, length histogram, and GC-vs-length plot.
• Emits JSON, TSV, HTML, and MultiQC custom-content JSON.
• Includes starter Nextflow, nf-core local module, and Snakemake examples.

Install From Release Assets

Download the archive for your platform, unpack it, and place fastaguard on PATH:

tar -xzf fastaguard-v0.1.0-x86_64-unknown-linux-gnu.tar.gz
./fastaguard-v0.1.0-x86_64-unknown-linux-gnu/fastaguard --help

macOS Intel and Apple Silicon archives are also built by the release workflow.

Docker

docker build -t fastaguard:local .
docker run --rm -v "$PWD:/data" fastaguard:local /data/sample.fa \
  --profile assembly \
  --out /data/fastaguard_report.html \
  --json /data/fastaguard.json \
  --tsv /data/fastaguard.tsv \
  --multiqc /data/fastaguard_mqc.json

Example Command

fastaguard sample.fa \
  --profile assembly \
  --out fastaguard_report.html \
  --json fastaguard.json \
  --tsv fastaguard.tsv \
  --multiqc fastaguard_mqc.json

Exit Codes

0 = pass
1 = warnings above configured threshold
2 = hard QC failure
3 = invalid input / tool error

Known Limits

• v0.1.0 supports the assembly profile only.
• FastaGuard does not estimate biological completeness, taxonomic contamination, or assembly correctness.
• Use QUAST, BUSCO, BlobToolKit, CheckM, and related tools after FASTA preflight depending on the biological question.
• Windows binaries, Bioconda, Homebrew, upstream nf-core submission, and official Snakemake wrapper submission are planned later.