Add construct-aware paired-guide decoding to screening

[Yifan1835]

Summary

• add an opt-in --screening_count_method crisprdecode counting path to the screening workflow while retaining MAGeCK as the default
• validate a headered paired-guide construct library and perform conservative exact assignment from synchronized R1/R2 reads
• report unique, ambiguous, unassigned and extraction-failed reads without arbitrary assignment of duplicate observable signatures
• aggregate a MAGeCK-compatible count matrix and per-sample/library-recovery QC, with assignment metrics included in MultiQC
• add schema validation, usage/output documentation, an immutable Python container reference and a deterministic synthetic truth fixture

Motivation

The existing screening path assumes that one sequenced spacer identifies one sgRNA. Paired-guide libraries encode construct identity using two observed guide elements, so treating each read as a conventional single guide can lose construct identity and conceal ambiguous signatures. This contribution adds a bounded construct-aware count-generation path that rejoins the existing workflow at ch_counts; downstream CRISPRcleanR, MAGeCK, BAGEL2, DrugZ and HitSelection behavior is unchanged.

User impact

Users can select paired-guide counting with:

--screening_count_method crisprdecode

The construct library is a headered TSV with construct_id, target_id, spacer_r1 and spacer_r2. Optional per-read anchor, offset and reverse-complement parameters describe the supported read geometry. The default value remains mageck, and a regression nf-test verifies the existing MAGeCK route.

Validation

• python3 -m unittest discover -s tests/crisprdecode -v — 6 tests passed
• nf-test 0.9.3 with Nextflow 25.04.0 — 2 subworkflow tests and 2 screening routing tests passed
• exact synthetic truth assertions cover unique assignment, duplicate-signature ambiguity, unassigned reads, extraction failure and zero-count constructs
• negative tests cover malformed libraries, desynchronized FASTQs, unequal record counts and invalid offsets
• nextflow run main.nf --help with Nextflow 25.04.0 passed full workflow parsing
• repository pre-commit hooks, JSON/YAML validation and git diff --check passed
• nf-core 3.5.1 lint was run; branch-specific snapshot and subworkflow metadata findings were addressed, while the remaining logo-template failures were already present on the upstream base

The repository's latest-everything Nextflow matrix is allowed to fail. Locally, Nextflow 26.04.6 fails before this implementation executes because nf-test 0.9.3 generates strict-syntax-incompatible *input; the required 25.04.0 matrix passes.

Scope

This MVP supports paired-end paired-guide libraries with exact matching and one downstream target label per construct. UMI/iBAR processing, pooled pegRNA libraries and combinatorial two-target statistical models remain out of scope.

Closes #278