ehsanestaji · ehsanestaji · Jul 16, 2026 · Jul 15, 2026 · Jul 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -105,9 +105,10 @@ The release strategy is evidence before expansion:
 v0.3: evidence pack + assembly gate + provenance checksums
 v0.4: compare mode for many FASTA files
 v0.5: submission readiness gate
-v0.6: transcriptome profile
-v0.7: protein profile
-v0.8: reference-panel profile
+v0.6: workflow-compatible exit contract
+v0.7: transcriptome profile
+v0.8: protein profile
+v0.9: reference-panel profile
 later: MCP/tool-agent interface and optional local summaries
 ```
 
@@ -123,20 +124,20 @@ Default product boundaries:
 Recommended next big release:
 
 ```text
-v0.5 should make submission readiness concrete before adding broad new biological profiles.
+v0.6 should simplify workflow integration before adding broad new biological profiles.
 ```
 
 The next planned feature direction is:
 
 ```text
-Submission Readiness Gate: --gate submission with --submission-target generic|ncbi.
+Workflow-Compatible Exit Contract: successful reports exit 0; report fields carry QC status.
 ```
 
-This should stay FASTA-level and database-free. It should check identifier
-safety, duplicate first-token IDs, unsafe characters, long identifiers, gap-like
-N runs, high ambiguity, and tiny-record advisories. It must not claim repository
-acceptance, biological completeness, annotation correctness, or contamination
-confirmation.
+This should keep JSON and TSV as the source of truth. Successful report
+generation should exit `0`, including WARN and FAIL reports. Argument parsing
+errors should exit `2`; configuration, input-access, and runtime errors should
+exit `3`. Existing v0.5 workflow integrations should keep compatibility handling
+until v0.6 packages and containers are published.
 
 ## Collaboration Preference
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "fastaguard"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2021"
 license = "MIT"
 description = "FASTA preflight QC for assembly pipelines"

diff --git a/README.md b/README.md
@@ -49,7 +49,7 @@ downstream tool.
 
 | Channel | Status |
 | --- | --- |
-| Source/package metadata | `v0.5.0` is the latest tagged source release |
+| Source/package metadata | This branch prepares `v0.6.0`; `v0.5.0` remains the latest tag |
 | GitHub release | v0.5 GitHub release binaries are built from the `v0.5.0` tag |
 | Bioconda | `v0.5.0` is live for Linux and macOS x86_64/ARM64 |
 | BioContainers | `v0.5.0` is live as a pinned workflow image |
@@ -123,6 +123,7 @@ fastaguard --version
 The `--gate pipeline` examples below require FastaGuard `v0.3.0` or newer.
 The `fastaguard compare` example requires FastaGuard `v0.4.0` or newer.
 The `--gate submission` example requires FastaGuard `v0.5.0` or newer.
+The conventional exit contract below starts with FastaGuard `v0.6.0`.
 
 Run the assembly preflight check:
 
@@ -142,10 +143,10 @@ fastaguard sample.fa --profile assembly --gate pipeline
 ```
 
 The `pipeline` gate is the v0.3 assembly preset for workflow stop/go decisions.
-It fails on duplicate IDs, invalid characters, invalid FASTA structure, and
-high-N content. GC and length outliers remain advisory by default because they
-are routing signals, not proof of contamination or misassembly. To make an
-advisory finding block a pipeline, add it explicitly with `--fail-on`.
+It marks duplicate IDs, invalid characters, invalid FASTA structure, and high-N
+content as blocking findings. GC and length outliers remain advisory by default
+because they are routing signals, not proof of contamination or misassembly. To
+mark an advisory finding as blocking, add it explicitly with `--fail-on`.
 
 v0.4 compare starter example:
 
@@ -197,15 +198,21 @@ Published BioContainers provides the v0.5 image for workflow engines:
 docker pull quay.io/biocontainers/fastaguard:0.5.0--hfa8f182_0
 ```
 
-Exit codes:
+Starting with FastaGuard v0.6.0, exit codes are:
 
 ```text
-0 = pass
-1 = warnings above configured threshold
-2 = hard QC failure
-3 = invalid input / tool error
+0 = command completed and requested outputs were written
+2 = argument parsing error
+3 = configuration, input-access, or runtime error
 ```
 
+QC PASS/WARN/FAIL decisions are recorded in the machine-readable outputs,
+especially `verdict.status`, `gate.status`, and `gate.blocking_findings`.
+Workflow engines should route on those fields instead of interpreting QC
+findings from the process exit code. 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.
+
 ## Product Thesis
 
 FASTA files are everywhere, but FASTA QC is fragmented across ad hoc scripts, `seqkit stats`, assembly QC tools, completeness tools, contamination workflows, and pipeline-specific checks. Each is useful, but none is the simple default first command for:
@@ -261,7 +268,7 @@ v0.2 expands the assembly preflight layer with:
 
 v0.3 adds the assembly gate contract:
 
-- `--gate pipeline` for default workflow blocking behavior
+- `--gate pipeline` for the default workflow gate policy
 - `gate.blocking_findings` for machine stop/go decisions
 - checksum provenance with `provenance.input_sha256`
 - explicit advisory findings for evidence that should route follow-up QC rather
@@ -285,6 +292,15 @@ v0.5 adds the submission-readiness gate:
 - boundaries that keep FastaGuard upstream of official validators, NCBI FCS,
   annotation validation, QUAST, BUSCO, BlobToolKit, and CheckM
 
+v0.6 makes report generation workflow-compatible:
+
+- successful report generation exits `0` for PASS, WARN, and FAIL reports
+- argument parsing errors exit `2`; configuration, input-access, and runtime
+  errors exit `3`
+- single-file TSV reports include `input_path` for downstream routing
+- workflows enforce QC policy from stable report fields instead of process
+  status
+
 ## Positioning
 
 FastaGuard should recommend deeper tools when they are appropriate:
@@ -324,6 +340,7 @@ FastaGuard catches FASTA-level assembly problems before expensive assembly QC.
 - [v0.5 submission readiness evidence](docs/evidence/fastaguard-v0.5-submission-readiness.md)
 - [v0.5 public evidence workflow](docs/evidence/fastaguard-v0.5-public-evidence.md)
 - [Packaging](docs/packaging.md)
+- [v0.6.0 release notes](docs/releases/v0.6.0.md)
 - [v0.5.0 release notes](docs/releases/v0.5.0.md)
 - [v0.4.0 release notes](docs/releases/v0.4.0.md)
 - [v0.3.0 release notes](docs/releases/v0.3.0.md)

diff --git a/docs/mvp-spec.md b/docs/mvp-spec.md
@@ -150,21 +150,27 @@ Default WARN conditions:
 
 ## Exit Codes
 
+Starting with FastaGuard v0.6.0:
+
 ```text
-0 = pass
-1 = warnings above configured threshold
-2 = hard QC failure
-3 = invalid input / tool error
+0 = command completed and requested outputs were written
+2 = argument parsing error
+3 = configuration, input-access, or runtime error
 ```
 
+QC PASS/WARN/FAIL decisions are report fields, not process-failure signals.
+Pipelines should read `verdict.status`, `gate.status`, and
+`gate.blocking_findings` from JSON/TSV outputs. Single-file TSV reports include
+`input_path`, `verdict`, and `gate_status` for downstream routing.
+
 ## Success Criteria
 
 The first release is successful if:
 
 - it validates huge FASTA files without loading full sequences into memory
 - it produces useful HTML, JSON, TSV, and MultiQC-compatible outputs
 - it catches invalid FASTA structure, duplicate IDs, invalid characters, and high-N content
-- it has deterministic, documented exit codes
+- it has deterministic, documented status fields and tool-error exit codes
 - it can be added to a Nextflow or Snakemake pipeline in under 5 minutes
 
 ## Implementation Status
@@ -174,5 +180,5 @@ The v0.1 assembly MVP is implemented as a Rust CLI with:
 - streaming FASTA parsing for plain and gzipped files
 - assembly metrics
 - explainable findings
-- deterministic verdict exit codes
+- deterministic verdict status fields
 - JSON, TSV, HTML, and MultiQC-compatible outputs
diff --git a/docs/output-contract.md b/docs/output-contract.md
@@ -4,7 +4,7 @@
 
 FastaGuard should be pipeline-native from the first release.
 
-The output contract is as important as the HTML report. Pipeline authors need stable field names, deterministic behavior, documented exit codes, and versioned schemas.
+The output contract is as important as the HTML report. Pipeline authors need stable field names, deterministic behavior, documented tool-error exit codes, and versioned schemas.
 
 ## Artifacts
 
@@ -29,6 +29,23 @@ fastaguard_compare_mqc.json
 v0.5 adds submission-readiness gate fields to the same JSON, TSV, HTML,
 MultiQC, and compare artifacts. JSON remains the source of truth.
 
+v0.6 separates process execution from QC status. Successful report generation
+returns exit code `0` for PASS, WARN, and FAIL reports.
+
+## Process Exit Contract
+
+Starting with FastaGuard v0.6.0:
+
+```text
+0 = command completed and requested outputs were written
+2 = argument parsing error
+3 = configuration, input-access, or runtime error
+```
+
+Workflow engines should apply stop/go policy from `gate.status`,
+`gate.blocking_findings`, or `verdict.status`. Process status only indicates
+whether FastaGuard completed the requested command and reports.
+
 ## JSON Contract
 
 Example v0.3 shape:
@@ -416,7 +433,8 @@ Recommended first rows:
 
 ```text
 metric	value
-schema_version	0.3.0
+schema_version	0.5.0
+input_path	sample.fa
 profile	assembly
 verdict	FAIL
 gate_mode	pipeline

diff --git a/docs/packaging.md b/docs/packaging.md
@@ -135,7 +135,7 @@ Keep future releases compatible with Bioconda expectations:
 - keep a single static-ish CLI binary target
 - keep deterministic tests and tiny fixtures
 - avoid runtime databases for early releases
-- maintain stable exit codes
+- keep process exit codes reserved for CLI/tool execution errors
 - maintain a versioned JSON Schema
 
 Bioconda recipe guidance checked for this setup:

diff --git a/docs/releases/v0.6.0.md b/docs/releases/v0.6.0.md
@@ -0,0 +1,31 @@
+# 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.
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -27,7 +27,7 @@ Capabilities:
 - GC-vs-length plot data and HTML plot
 - PASS / WARN / FAIL verdict
 - JSON, TSV, HTML, and MultiQC-compatible outputs
-- deterministic exit codes
+- deterministic report status fields
 
 ## v0.2: Assembly Trust + Pipeline Adoption
 
@@ -118,7 +118,25 @@ Development scope:
 - FastaGuard does not replace NCBI, ENA, DDBJ official validators or guarantee
   repository acceptance
 
-## v0.6: Transcriptome Profile
+## v0.6: Workflow-Compatible Exit Contract
+
+Goal:
+
+```text
+Separate command execution from FASTA quality decisions in workflow engines.
+```
+
+Development scope:
+
+- return exit code `0` whenever requested reports are written successfully,
+  including WARN and FAIL reports
+- reserve exit code `2` for argument parsing errors
+- reserve exit code `3` for configuration, input-access, and runtime errors
+- keep PASS/WARN/FAIL decisions in stable JSON and TSV report fields
+- include `input_path` in single-file TSV reports for downstream routing
+- document migration from legacy QC-derived process exit codes
+
+## v0.7: Transcriptome Profile
 
 Potential additions:
 
@@ -128,7 +146,7 @@ Potential additions:
 - extreme GC outliers
 - isoform-heavy warning heuristics
 
-## v0.7: Protein Profile
+## v0.8: Protein Profile
 
 Potential additions:
 
@@ -138,7 +156,7 @@ Potential additions:
 - low-complexity regions
 - suspicious nucleotide-looking proteins
 
-## v0.8: Reference Panel Profile
+## v0.9: Reference Panel Profile
 
 Potential additions:
 

diff --git a/docs/tool-landscape.md b/docs/tool-landscape.md
@@ -56,7 +56,7 @@ Without FastaGuard, users typically combine several partial checks:
 - run QUAST for assembly metrics
 - run BUSCO for biological completeness
 - run BlobToolKit or taxonomy tooling for contamination exploration
-- rely on pipeline-specific assumptions for exit codes and report parsing
+- rely on pipeline-specific assumptions for report parsing and stop/go policy
 
 That works, but it is fragmented. The missing layer is a default, explainable,
 machine-readable FASTA preflight contract.

diff --git a/docs/use-cases.md b/docs/use-cases.md
@@ -56,11 +56,12 @@ spend time on bad input.
 ### Pipeline Gate For Workflow Engines
 
 FastaGuard gives Nextflow, Snakemake, nf-core, Galaxy, and institutional
-pipelines a simple PASS/WARN/FAIL decision with deterministic exit codes and
-structured evidence.
+pipelines a simple PASS/WARN/FAIL decision with structured evidence in JSON,
+TSV, HTML, and MultiQC-compatible outputs.
 
 Pipelines can stop early on hard FASTA failures, continue with warnings, or
-route samples to follow-up tools based on machine-readable findings.
+route samples to follow-up tools based on machine-readable fields such as
+`gate.status` and `gate.blocking_findings`.
 
 ### Batch Triage With Compare Mode