Add reproducible assay handoff bundles

README.md

@@ -116,6 +116,18 @@ Review `crispr_screen/inference_report.json` and `assay.toml`, then run:
 dotmatch assay start crispr_screen/assay.toml
 ```
 
+After a completed run, create a compact technical review bundle without copying
+raw FASTQs:
+
+```bash
+dotmatch assay handoff crispr_screen/assay.toml
+```
+
+The bundle includes configuration, QC, reports, methods, citation material, and
+checksums for declared inputs and copied outputs. See the [lab evaluation and
+handoff guide](https://dotmatch.readthedocs.io/en/latest/lab-evaluation.html)
+for the review sequence and data-handling boundary.
+
 For an explicit one-command run, use `dotmatch crispr-count`. The
 [CRISPR tutorial](https://dotmatch.readthedocs.io/en/latest/tutorials/crispr-count-first-run.html)
 covers both routes.
@@ -212,6 +224,7 @@ replaces general alignment or every demultiplexing workflow.
 - [Getting started](https://dotmatch.readthedocs.io/en/latest/getting-started.html)
 - [Command reference](https://dotmatch.readthedocs.io/en/latest/command-reference.html)
 - [AssaySpec workflows](https://dotmatch.readthedocs.io/en/latest/assayspec.html)
+- [Lab evaluation and handoff](https://dotmatch.readthedocs.io/en/latest/lab-evaluation.html)
 - [CRISPR count QC](https://dotmatch.readthedocs.io/en/latest/crispr-qc.html)
 - [Barcode panel design](https://dotmatch.readthedocs.io/en/latest/barcode-panel-design.html)
 - [Output schemas](https://dotmatch.readthedocs.io/en/latest/schemas.html)

docs/assayspec.md

@@ -21,6 +21,7 @@ dotmatch assay run assay.toml
 dotmatch assay init --template crispr --out assay.toml
 dotmatch assay infer --mode count --assay-type crispr --targets guides.csv --reads sample.fastq.gz --out assay.toml --report inference_report.json
 dotmatch assay autopsy assay.toml --out-dir autopsy/
+dotmatch assay handoff assay.toml
 ```
 
 `start` is the default production entrypoint: it runs `check`, then `run`, and
@@ -71,6 +72,12 @@ relaxed with `[reliability] fail_on_draft_inference = false`.
 `top_unmatched.*.tsv` files. `run` also triggers autopsy automatically when
 sample QC crosses conservative thresholds.
 
+`handoff` creates `<out_dir>/handoff/` after a completed run. It copies a
+review-sized set of reports, configuration, QC, count, methods, and citation
+files; writes `SHA256SUMS`; and records SHA-256 hashes for every declared input.
+It does not copy FASTQ files, so raw reads remain in the originating controlled
+workspace. Use `--out-dir PATH` to write the bundle to an empty directory.
+
 ## Count Example
 
 ```toml

docs/command-reference.md

@@ -56,12 +56,17 @@ dotmatch assay optimize assay.toml
 dotmatch assay plan assay.toml
 dotmatch assay run assay.toml
 dotmatch assay autopsy assay.toml --out-dir autopsy/
+dotmatch assay handoff assay.toml
 ```
 
 `start` is the production entrypoint: it checks the spec, runs assignment, and
 prints the reliability verdict. `optimize` writes an advisory CPU/GPU backend
 recommendation; it does not change the count authority.
 
+`handoff` creates a review bundle after a completed run. It includes the
+configuration, reports, QC, count outputs, methods, citation material, and
+SHA-256 records for inputs and copied files, without copying raw FASTQs.
+
 Supported templates include `crispr`, `feature-barcode`,
 `inline-barcode-count`, `inline-barcode-demux`, `amplicon-panel`,
 `oligo-adapter`, and `pair-count`.

docs/getting-started.md

@@ -225,6 +225,8 @@ default policy.
 
 - Use [AssaySpec](assayspec.md) for the full `assay new`, `start`, `check`, and
   `run` command reference.
+- Use [Lab Evaluation and Handoff](lab-evaluation.md) when a completed run
+  needs a review package without moving raw reads.
 - Use [Command Reference](command-reference.md) for the current command map.
 - Use [CRISPR Count QC](crispr-qc.md) before downstream screen statistics.
 - Use [Barcode Panel Design](barcode-panel-design.md) when creating or checking

docs/index.md

@@ -33,6 +33,7 @@ the [command reference](command-reference.md).
 | --- | --- |
 | Count guides from a CRISPR screen | [CRISPR first run](tutorials/crispr-count-first-run.md) |
 | Build a checked assay project | [AssaySpec workflows](assayspec.md) |
+| Evaluate and hand off a run | [Lab evaluation and handoff](lab-evaluation.md) |
 | Split reads by inline barcode | [Getting started: demultiplexing](getting-started.md#demultiplex-inline-barcodes) |
 | Diagnose barcode failures | [Barcode run diagnosis](getting-started.md#diagnose-a-barcode-run) |
 | Design or check a barcode panel | [Barcode panel design](barcode-panel-design.md) |
@@ -72,6 +73,7 @@ getting-started
 command-reference
 tutorials/crispr-count-first-run
 tutorials/scverse-perturb-seq
+lab-evaluation
 ```
 
 ```{toctree}

docs/lab-evaluation.md

@@ -0,0 +1,94 @@
+# Lab Evaluation and Handoff
+
+This guide is for a bioinformatics team or core facility evaluating DotMatch on
+a known-target sequencing assay. It is a local technical evaluation protocol,
+not a clinical validation protocol and not a substitute for assay-specific
+controls.
+
+## Before processing study data
+
+Confirm all of the following with the assay owner:
+
+- the target library is the intended revision and contains only the expected
+  fixed-window sequences;
+- the FASTQ read and orientation are known, along with the start and length of
+  the target window;
+- the permitted edit radius and ambiguity policy have been chosen deliberately;
+- sample identifiers and FASTQ paths have been checked against the run sheet;
+- the intended downstream consumer of the output is known. For CRISPR counts,
+  DotMatch writes a MAGeCK-style matrix but does not perform screen statistics.
+
+Create a reviewable project from the release package:
+
+```bash
+dotmatch assay new crispr \
+  --library guides.csv \
+  --reads-dir fastqs/ \
+  --out crispr_evaluation/
+
+cd crispr_evaluation
+dotmatch assay check assay.toml
+```
+
+`assay new` samples the input reads to propose an extraction window. Review
+`inference_report.json`, the target-library audit, and the generated
+`assay.toml`. Keep `status = "draft"` until a qualified reviewer has confirmed
+the configuration, then set it to `ready`.
+
+## Run and review
+
+```bash
+./run.sh
+dotmatch assay handoff assay.toml
+```
+
+`./run.sh` uses `dotmatch assay start`: it runs preflight, assignment, target
+audit, QC, and validation. Open these files in order:
+
+1. `assay_out/reliability_report.html`
+2. `assay_out/sample_qc.tsv` and `assay_out/crispr_qc.html` for CRISPR runs
+3. `assay_out/assay_report.html`
+4. `assay_out/counts.mageck.tsv` or the primary count/demultiplexing output
+5. `assay_out/methods.md` and `assay_out/CITATION.bib`
+
+Do not treat a `passed` DotMatch reliability verdict as proof of biological
+validity. It means the configured target safety and software QC rules passed.
+Review positive/negative controls, sample identity, sequencing-run metrics,
+replicate agreement, and downstream analysis according to the local assay
+protocol.
+
+## Handoff package
+
+`dotmatch assay handoff assay.toml` writes `assay_out/handoff/` without copying
+raw reads. The bundle is suitable for an internal technical review or a
+workflow-maintainer evaluation:
+
+- `README_FOR_REVIEW.md` states the review order and boundary;
+- `handoff_manifest.json` records the configuration, verdict, input file sizes,
+  and input/output SHA-256 hashes;
+- `SHA256SUMS` verifies the copied review files;
+- `review/` contains reports, QC tables, primary outputs, methods, citation,
+  and software-version records.
+
+In the controlled workspace containing the FASTQs, recompute each input hash
+in `handoff_manifest.json` before approving the handoff. Do not send raw reads
+or identifiers outside the approved data-handling route merely to make a
+DotMatch review bundle.
+
+## Decision record
+
+For each evaluated assay, record:
+
+| Item | Record |
+| --- | --- |
+| Assay and target-library revision | Name, source, checksum, and owner |
+| Read extraction | Read, orientation, start, length, and rationale |
+| Assignment rules | Metric, edit radius, ambiguity policy, and handling of ambiguous reads |
+| Input identity | Sample-sheet revision and FASTQ checksums |
+| QC outcome | Reliability verdict, findings reviewed, controls, and any exceptions |
+| Output recipient | Count matrix/report location and downstream analysis owner |
+| Software record | DotMatch version, native version, `methods.md`, and `CITATION.bib` |
+
+Keep this record with the project or laboratory notebook. It makes a later
+rerun auditable without claiming that DotMatch replaces the remainder of the
+assay or analysis workflow.

docs/tutorials/crispr-count-first-run.md

@@ -48,6 +48,17 @@ Key outputs under the configured `out_dir`:
 CPU remains the assignment authority. GPU Metal is opt-in via `[backend]` in the
 assay spec and requires `--metal-validate` when enabled.
 
+After a completed run, create a review package without copying raw FASTQs:
+
+```bash
+dotmatch assay handoff crispr_assay.toml
+```
+
+This writes `assay_out/handoff/`, including reports, primary outputs, methods,
+citation material, and SHA-256 records for the declared inputs. See [Lab
+Evaluation and Handoff](../lab-evaluation.md) for the review order and
+acceptance record.
+
 ## 3. Direct `crispr-count` (single command)
 
 For a minimal single command without the full assay wrapper: