Add lab release acceptance gate

MANIFEST.in

@@ -2,5 +2,6 @@ graft examples
 include scripts/__init__.py
 include scripts/validation/__init__.py
 include scripts/validation/check_distribution.py
+include scripts/validation/check_release_gate.py
 prune data
 global-exclude *.npy *.npz *.pkl

TODO.md

@@ -111,8 +111,8 @@ Reporting integration:
 
 ## 4. Real-Data End-To-End Validation
 
-**Status:** In progress; clean structural end-to-end validation is complete,
-but biological equivalence and production acceptance remain open.
+**Status:** Core technical release acceptance is complete; biological
+equivalence and clinical/biomarker validation remain open.
 
 Completed validation used one control and one sALS sample, each deterministically
 subsampled to five million paired reads. The managed Twist/hg38 workflow ran
@@ -145,26 +145,42 @@ validated, and all 95 run-summary links resolved. A second `cftk run` resumed
 all seven stages and executed zero external commands. The resulting matrix has
 420,435 CpGs and two sample columns.
 
-Implementation:
+The maintainer release gate now verifies the preserved clean attempt and its
+immediate resume directly from their immutable manifests. The accepted pair
+has seven clean then seven resumed stages, 24 paired zero-exit clean commands,
+an empty resume command ledger, 26 passing doctor checks, 11 passing tool
+probes, and 72 valid required artifacts. Machine-readable and text evidence is
+written only to the private validation workspace and omits commands, paths,
+sample-derived filenames, sample identifiers, and patient-level values. This
+gate adds no biological or numerical acceptance threshold.
+
+Completed implementation:
 
-- Preserve the approved smoke inputs, managed reference profile, tool versions,
+- [x] Preserve the approved smoke inputs, managed reference profile, tool versions,
   checksums, external validation recipe, and generated reports outside Git.
-- Repeat the complete workflow from a clean project so the command ledger also
+- [x] Repeat the complete workflow from a clean project so the command ledger
   includes stages that were reused from checkpoints during the successful retry.
-- Compare commands and key outputs with the Twist technical note, including
+- [x] Compare commands and key outputs with the Twist technical note, including
   read groups, mapping filters, target metrics, `--mergeContext`, minimum depth,
   and OT/OB handling.
-- Keep the default workflow on Sambamba; retain Picard as an explicit advanced
+- [x] Keep the default workflow on Sambamba; retain Picard as an explicit advanced
   `process.duplicate_marking_tool` option and keep any comparison internal.
-- Record runtime, memory, artifact checksums, expected ranges, and any accepted
-  version-specific differences.
+- [x] Add a repeatable maintainer gate for exact command completion, artifact
+  contracts, doctor/tool records, project identity, and zero-command resume.
+
+Remaining biological validation:
+
+- Record runtime, memory, artifact identities, tool-native diagnostic values,
+  and any accepted version-specific differences for future release candidates.
+- Define biological acceptance only for a separately designed, adequately
+  powered validation study; do not expose a technical cutoff to beginner users.
 
 Completion criteria:
 
 - Every external command exits successfully and produces its expected,
   nonempty artifacts.
-- Target coverage, alignment, duplicate, methylation, and QC outputs pass
-  predefined scientific and structural checks.
+- Target coverage, alignment, duplicate, methylation, and QC outputs satisfy
+  their existing structural contracts and preserve tool-default diagnostics.
 - The complete validation recipe and provenance are reproducible in a clean
   environment before a production release is tagged.
 

docs/user_guide/validation_acceptance.rst

@@ -230,3 +230,81 @@ does not copy BAMs, source tables, the private report, sample identifiers, or
 absolute paths. The generated figures are documentation evidence only; they
 must retain the explicit technical-example and targeted-panel limitations used
 on the public user-guide pages.
+
+Step 6: Run The Lab Release Gate
+--------------------------------
+
+This final check is for CFTK maintainers, not ordinary package users. It proves
+that one core Twist workflow attempt executed every applicable stage, that the
+recorded commands and required artifacts are complete, and that immediately
+repeating the unchanged workflow reused those artifacts without executing a
+command. It does not add a biological, numerical, or cross-tool threshold.
+
+Use a dedicated private validation project. The accepted clean attempt must
+record ``complete`` for every applicable stage; ``adopted`` or ``resumed`` is
+not a substitute for clean execution. Do not use ``--adopt-existing`` for that
+attempt. Capture the immutable manifest path before running the same command a
+second time:
+
+.. code-block:: bash
+
+   export PRIVATE_VALIDATION=/path/to/private/cftk_release_validation
+
+   cftk --config "$PRIVATE_VALIDATION/cftk_init.json" run
+   clean_run=$(jq -r '.manifest' \
+       "$PRIVATE_VALIDATION/results/provenance/latest-run.json")
+
+   # Do not edit the config, inputs, references, outputs, or run options.
+   cftk --config "$PRIVATE_VALIDATION/cftk_init.json" run
+   resume_run=$(jq -r '.manifest' \
+       "$PRIVATE_VALIDATION/results/provenance/latest-run.json")
+
+   python scripts/validation/check_release_gate.py \
+       --clean-run "$clean_run" \
+       --resume-run "$resume_run" \
+       --output-dir "$PRIVATE_VALIDATION/release-gate"
+
+The command exits ``0`` only when both manifests are complete, project and
+artifact identities agree, the second attempt points directly to the clean
+attempt, all clean stages are ``complete``, all resume stages are ``resumed``,
+every clean command has one zero-exit finish, the resume command ledger is
+empty, doctor has no failures, and every required artifact still satisfies its
+recorded nonempty contract. Artifact tables, event ledgers, tool-version
+records, and schema-version evidence are checked as well.
+
+The gate writes two deterministic records:
+
+.. code-block:: text
+
+   release-gate/
+   |-- release_acceptance.json
+   `-- release_acceptance.txt
+
+These records contain run IDs, project-identity hashes, core stage IDs and
+statuses, contract hashes, and aggregate counts. They intentionally omit input
+paths, commands, sample-derived filenames, sample identifiers, and patient-level
+values. Keep them in the private validation workspace and review them before
+sharing; never commit the private project, scheduler logs, or raw gate inputs.
+
+CFTK core run schemas 1 through 3 are supported. Schema 3 requires its
+integrated evidence bundle. Earlier complete manifests predate that bundle, so
+the gate validates their stable run-level records and artifact contracts
+directly and reports integrated evidence as not required.
+
+Scheduler use is optional and external to the gate. The same procedure is
+valid in a local process or an approved institutional allocation. If Slurm is
+used, submission and monitoring are advanced maintainer tasks: use the lab or
+institutional account, preserve the scheduler logs privately, and do not add
+account names or cluster-specific paths to this repository.
+
+Preserved Two-Sample Result
+---------------------------
+
+The preserved two-sample Twist technical pair passes this gate. The clean
+attempt completed all seven applicable stages with 24 paired zero-exit
+commands, 26 passing doctor checks, 11 passing tool probes, and all 72 required
+artifacts present (56 output/report rows and 16 figure rows). Its immediate
+successor resumed all seven stages with an empty command ledger and the same
+project, tool, stage, and artifact identities. This is execution and
+reproducibility evidence for a bounded technical example, not biological or
+clinical validation.

scripts/validation/check_distribution.py

@@ -37,6 +37,7 @@
     "scripts/__init__.py",
     "scripts/validation/__init__.py",
     "scripts/validation/check_distribution.py",
+    "scripts/validation/check_release_gate.py",
 }
 
 FORBIDDEN_SUFFIXES = {