Fix paralog cross-hits silently dropping syntenic blocks (--best_hmm_wins)

[Robaina]

Closes #96.

Problem

When the HMM panel passed to pynteny search contains paralogous models (e.g. nifD/nifK, nifE/nifN), the same peptide commonly scores above threshold under more than one HMM. Pynteny kept every hit, and the duplicate rows — interleaved by the (contig, gene_pos) sort between the rows of true syntenic neighbours — broke the position-diff check inside the rolling window. The result was a silent false negative: a genuine syntenic operon was dropped from synteny_matched.tsv with only an informational warning.

I confirmed the mechanism against the code: with cross-hits, the canonical triple (e.g. nifH@33, nifD@34, nifK@35) is never visited as a contiguous window because extra cross-hit rows sit between its members, so the (distance == 1,1) check never passes.

Fix

Add an opt-in --best_hmm_wins flag (default off, so existing behaviour and curated |-group panels are unchanged):

• SyntenyHMMfilter.get_all_HMM_hits() deduplicates by peptide (full_label), keeping the highest-scoring HMM, before the rolling-window scan. The HMMER bitscore is carried only on this path and dropped immediately after dedup, so the default code path keeps exactly the same columns/behaviour (this avoided a regression in _merge_hits_by_HMM_group's drop_duplicates).
• Flag threaded: CLI (-b/--best_hmm_wins) → synteny_search → filter_FASTA_by_synteny_structure → SyntenyHMMfilter, and through the api.Search class.
• The duplicate-hits warning is upgraded to report the count and the top offending HMM combinations, and to point users at --best_hmm_wins.
• Docs: search.md gains a "note on paralogous HMMs" section and the new flag in the options table; pynteny search --help documents it.

Tests

New tests/test_filter.py builds a minimal synthetic cross-hit scenario:

• test_default_drops_operon_on_crosshit — reproduces the silent drop (default behaviour).
• test_best_hmm_wins_recovers_operon — --best_hmm_wins recovers the full nifH→nifD→nifK operon.

Full suite: 26 passed (24 existing + 2 new); the existing |-group integration test still passes, confirming the default path is unchanged.

Scope notes

Following the issue's guidance, I did not change the rolling-window matcher itself (correct on deduplicated input), the degenerate-case sys.exit(1), or the default behaviour. The 2.0 default-flip is left for a future major release.

🤖 Generated with Claude Code