docs: clear fgbio-parity doc tail across commands (W11)

[nh13]

Summary

W11 of the final-audit burn-down: the docs / wontfix sweep. This is a documentation-only PR that clears the low-value fgbio/Picard-parity doc tail — help text, long_about, and shared-option doc comments — with no runtime, metric, or test changes. Each correction was verified against the actual code and the per-command audit files under reports/final-audit/.

Doc changes (finding → file → what changed)

Finding	File	Change
CLIP3-06	commands/clip.rs	long_about said "By default soft clipping is performed"; the actual default clipping mode is hard. Corrected.
CLIP3-07	commands/clip.rs	Documented that --metrics is produced only by the single-threaded path and cannot be combined with --threads.
FILT3-07	commands/filter.rs	Documented that --min-base-quality is optional in fgumi (required in fgbio) and that omitting it performs no per-base quality masking.
GRP3-02	commands/group.rs	Removed the stale "defaults to 0 in duplicate marking mode" note on --min-map-q (fgumi has no duplicate-marking mode in group; dedup handles it); state the default is 1.
GRP3-07	commands/group.rs	Documented that --threads sizes the whole read/assign/write pipeline in fgumi, unlike fgbio where it sizes only the UMI-comparison worker pool.
ZIP3-07	commands/zipper.rs	Documented that tag-list flags are comma-delimited in fgumi vs space-separated in fgbio's ZipperBams.
ZIP3-12	commands/zipper.rs	Documented that absent tags, or tags whose type does not support the requested transform, are silently skipped rather than raising an error.
DOWN3-01/02/03	commands/downsample.rs	Documented that fgumi downsample is a UMI-family sampler by design, not a Picard DownsampleSam port: different sampling unit (MI family vs read template), order-dependent per-family draw vs stateless name-hash, non-deterministic without --seed (vs Picard's fixed seed 1), and --fraction restricted to (0.0, 1.0].
SIMPLEX3-02	commands/simplex.rs	Documented that --max-reads downsampling uses a different PRNG than fgbio's Scala Random, so surviving reads (and the consensus of a downsampled family) are not bit-identical to fgbio (deterministic within fgumi).
SIMPLEX3-05	commands/common.rs	Documented --min-consensus-base-quality as an fgumi superset: default 2 matches fgbio, which hardcodes the minimum to MIN_PHRED (2) and defers masking to filter.
DUPLEX3-08	commands/common.rs	Documented that --output-per-base-tags default (true) matches fgbio and that setting it false drops per-base tags fgbio writes unconditionally.
DUPLEX3-09	commands/duplex.rs	Documented that --min-reads is comma-delimited in fgumi vs space-separated in fgbio.
CODEC3-09	commands/codec.rs	Mapped fgumi's --min-reads/--max-reads to fgbio's --min-read-pairs/--max-read-pairs in the flag help.
DXM3-08	commands/duplex_metrics.rs	Documented that paired templates missing the physical R2 record are skipped (non-issue for properly grouped/sorted BAMs).
DXM3-09	commands/duplex_metrics.rs	Documented the literal "Sample" default for --description (fgbio derives sample/library from the @RG header, so plot titles differ unless set).
SIMM3-04	commands/simplex_metrics.rs	Documented the literal "Sample" default for --description (as DXM3-09).
SIMM3-05	commands/simplex_metrics.rs	Documented that both BED and Picard interval-list formats are auto-detected (an fgumi superset; fgbio's analog accepts only the Picard interval list).

Excluded / skipped (not doc-only, or wrong base)

These findings from the same audit files were not touched here because they are behavior changes, wrong-base, or already resolved:

• RUN3-04 — lives in src/lib/commands/runall.rs on the feat-runall branch, not main. Different base; excluded.
• SORT3-10 (lexicographic → lexicographical) — changes an emitted @HD SS header value and a test that pins it (a behavior/round-trip change, marked "discuss"). Excluded; needs a disposition.
• FILT3-09 (drop the cc > ab error-rate rejection) — the described over-restriction is not present in current main: validate_parameters only enforces ab <= ba, which already matches fgbio. No change needed.
• ZIP3-09 (RG/PG declaration order) — the resulting header set is identical; nothing user-facing to correct. Wontfix.
• ZIP3-13 (am/bm methylation MM-strings unclassified) — disposition is "verify EM-seq duplex need"; adding these tags to a transform set would be a behavior change. Excluded pending verification.
• SIMPLEX3-03/06/07/08 — deep numeric edge cases (unanimous fast-path over-report, unclamped cD/cM, base-case sensitivity flip, single-input quality clamp), all unreachable under defaults, with no natural user-facing help surface. Noted, not changed.
• SIMPLEX3-04, DUPLEX3-07, SIMM3-03 — hardcoded standard tags / no --cell-tag; disposition "likely wontfix (opinionated standard-tag design)." Not a help-text correction.
• DUPLEX3-05 (dead --min-consensus-base-quality for duplex) — disposition "remove or wire" (behavior). Excluded.
• DUPLEX3-06, CODEC3-10 — --sort-order output re-sort (behavior/discuss) and MT chain string-vs-typed error match (code fix). Excluded.
• DUPLEX3-10 — zero-depth error-rate guard; fgumi safer, unreachable. Wontfix (see below).

Wontfix / not-a-gap set (recorded so it stops re-surfacing)

fgumi is correct or intentionally divergent in each of these; no change is warranted:

• EXT-02 — read-name UMI field-count ≥8 leniency; intentional (over-count sibling of the strict-throw path). fgumi accepts lenient input by design.
• EXT3-08 — extract CLI-surface divergence (missing --umi-tag/--cell-tag/--sort, repurposed short flags); intentional opinionated standard-tags-only design; defaults keep output correct.
• EXT3-09 — 8-field name with empty trailing field: fgumi returns None where fgbio emits an empty-string RX; fgumi is arguably more correct.
• FASTQ3-05 — /1,/2 appended by default (unless -n): diverges from Picard but matches samtools; sensible for the pipe-to-aligner use.
• FASTQ3-06 — non-PF and duplicates kept by default: matches samtools (Picard excludes non-PF); documented default.
• FASTQ3-07 — intentional single-stream design (no R1/R2/singleton split, per-RG, index-read, or interleave toggles); documented "pipe to aligner."
• ZIP3-01 — TC/template-coordinate tags added to secondary/supplementary by default: part of fgumi's template-coordinate-sort pipeline design (gated off by --skip-tc-tags); not an fgbio bug.
• FILT3-05 — fgumi's even-length per-base tag reversal is correct; fgbio has an off-by-one bug (interior pairs never swapped for even n). Do not "fix toward" fgbio.
• FILT3-10 — empty-read no-call edge: fgumi guards seq_len > 0 and keeps; fgbio drops on NaN. Unreachable for real consensus reads; fgumi safer.
• DEDUP-01 — fgumi adds no mapq to the duplicate score, matching Picard SUM_OF_BASE_QUALITIES (fgbio adds mapq); fgumi is a Picard drop-in.
• DEDUP-03 — fgumi keeps + marks secondary/supplementary of a duplicate template (Picard also flags them); fgbio discards them. fgumi is closer to Picard.
• CLIP3-04 — N/skip excluded from ref-consumption in the clip loop; deliberate to keep the raw and typed clippers byte-identical. Affects only spliced/RNA reads (rare in UMI workflows).
• SORT-01 — template-coordinate name tie-break uses a 63-bit hash, not lexical; deterministic with negligible collision probability, no grouping impact; only breaks byte-identity with samtools sort --template-coordinate.
• DXM3-10-class — the family of NaN/±inf/overflow/divide-by-zero guards that fgbio lacks (e.g. DUPLEX3-10, FILT3-10): fgumi is safer on unreachable edges. Wontfix.

Testing

• cargo ci-fmt — clean
• cargo ci-lint — clean (features compare,simulate,profile-adjacency)
• cargo ci-test — 2267 passed, 22 skipped, 0 failed
• cargo test --doc — 34 passed, 0 failed

Summary by CodeRabbit

• Documentation
  • Clarified clipping defaults, metrics limitations, and read-pair downsampling options.
  • Expanded consensus-calling guidance for per-base tags and quality masking.
  • Documented downsampling differences, validation rules, determinism, and compatibility expectations.
  • Clarified input formatting for duplex options and tag-reversal settings.
  • Improved guidance for paired templates, plot descriptions, interval formats, mapping quality defaults, threading, and duplicate marking.
  • Documented simplex downsampling behavior and handling of missing or unsupported tags.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0e101bf5-cb6e-4e1c-a10c-43bdcead85fa

📥 Commits

Reviewing files that changed from the base of the PR and between f55ac4b and da72c12.

📒 Files selected for processing (11)

• src/lib/commands/clip.rs
• src/lib/commands/codec.rs
• src/lib/commands/common.rs
• src/lib/commands/downsample.rs
• src/lib/commands/duplex.rs
• src/lib/commands/duplex_metrics.rs
• src/lib/commands/filter.rs
• src/lib/commands/group.rs
• src/lib/commands/simplex.rs
• src/lib/commands/simplex_metrics.rs
• src/lib/commands/zipper.rs

---

Walkthrough

Documentation-only changes update CLI help and module descriptions across commands, clarifying defaults, execution constraints, input formats, and behavioral differences from fgbio and Picard. No runtime logic, option wiring, or public declarations changed.

Changes

CLI documentation alignment

Layer / File(s)	Summary
Command help and behavior documentation src/lib/commands/*.rs	Help text documents clipping defaults, metrics restrictions, consensus masking, downsampling, threading, read limits, interval formats, mate handling, plot titles, and tag-list behavior.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the doc-only cleanup of fgbio-parity notes across multiple commands.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch nh/docs-parity-sweep

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.84%. Comparing base (f55ac4b) to head (da72c12).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #558   +/-   ##
=======================================
  Coverage   92.84%   92.84%           
=======================================
  Files         166      166           
  Lines      102064   102064           
=======================================
+ Hits        94765    94766    +1     
+ Misses       7299     7298    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.