feat(dedupe): injectable candidate scope and winner order, plus dedupe pools docs

[blakeaowens]

Description

Two related changes: a small seam in the deduplication engine, and the documentation for the Pro
feature built on top of it.

The seam. build_candidate_scope_queryset() decides which existing findings a new finding is
compared against, and the winner order decides which one becomes the original. Both were computed
internally with no way for a caller to influence them. This adds two optional keyword arguments,
candidate_qs and ordering_key, threaded through the finders, the candidate generators, the
batch matchers and both dispatchers, plus a scope_filter on the false-positive-history path.

Nothing changes when they are not supplied. Every call site forwards them only when set:

scope_kwargs = {}
if candidate_qs is not None:
    scope_kwargs["candidate_qs"] = candidate_qs
if ordering_key is not None:
    scope_kwargs["ordering_key"] = ordering_key

so the default path builds exactly the queryset and ordering it always did. The seam is
deliberately queryset-shaped rather than a callback or a settings flag: a caller narrows or widens
the candidate set by handing in a queryset, and the engine keeps ownership of how matching itself
works.

The documentation covers DefectDojo Pro's dedupe pools, which are the first consumer of the
seam: named groups of Assets whose findings deduplicate against each other, per matching kind.
The new page explains what a pool does and does not do (it changes which findings are eligible to
be compared, never how two are compared), why the reimport kind cannot widen scope even though it
appears alongside the two kinds that can, and the preview-then-acknowledge contract on the
retroactive actions.

Three existing statements became incomplete rather than wrong once pools exist, so they are
updated in the same change: the scope paragraph and the Pro algorithm summary in About
Deduplication, and that page's troubleshooting table, which previously offered only instance-wide
answers to a per-Asset scope problem. The Enabling Deduplication intro gains a pointer.

Test results

unittests/test_dedupe_injectable_scope.py is new and covers the seam directly: that an injected
queryset narrows and widens the candidate set, that an injected ordering key selects the original,
that omitting both reproduces the default scope and order exactly, that the false-positive
history path honours the same filter, and (in its second class) that the history scope hook is
consulted only when the caller passed no scope.

Run locally against a Pro-flavoured checkout:

python manage.py test unittests.test_dedupe_injectable_scope unittests.test_dedupe_flush_missing_original

21 tests (17 in the scope module, 4 in the flush module), all passing, and the new file is clean
under the OSS ruff pin. The wider deduplication suites were also run green on the consuming side.

False-positive history scope hook

do_false_positive_history_batch now asks the FINDING_FALSE_POSITIVE_HISTORY_SCOPE_METHOD
custom method for its search scope when the caller passes none, the same mechanism as the
existing candidate-filter hook. Without it, the post-import task (which passes no scope) always
searched the finding's own product, so a plugin that widens deduplication to a group of
products could not widen the history search the same way. A provider returns filter keyword
arguments or None; an explicit scope_filter from the caller is never second-guessed, and
with no provider configured the default is unchanged. Four tests pin the default, the provider,
a None answer, and the caller's precedence.

Release ordering

This has to land first, or in the same release train as the DefectDojo Pro change that consumes
it. That change calls the new signature in nine places (eight forwarding call sites on the finders
plus one direct call to build_candidate_scope_queryset), so against a released engine without
candidate_qs every one of them raises a TypeError. Both are milestoned for the same release,
which satisfies the constraint; the note is here so a later retarget of either one does not
quietly break the pairing.

The same ordering matters for the history hook, in a quieter way. An engine without
FINDING_FALSE_POSITIVE_HISTORY_SCOPE_METHOD support ignores the setting: nothing raises, but a
false positive marked in one pooled Asset no longer reaches a sibling on import, and the only
symptom is a Finding that stays active. So the pairing is a behaviour dependency as well as a
signature one.

The reverse direction is safe: both parameters default to None and reproduce the previous
queryset and ordering exactly, so this engine works unchanged with no consumer at all.

Documentation

Included in this PR, under docs/content/triage_findings/finding_deduplication/, plus a 3.3.0
section in docs/content/releases/pro/changelog.md carrying the two behaviour changes the Pro PR
introduces (false-positive history follows deduplication scope; the three global algorithms,
Global Component, Global Vulnerability ID and Global Locations, bounded to the pool for a pooled
Asset) and the two feature lines. The
dedupe-pools page states the Apply Now ceiling (10,000 Findings) and the tuning page describes
what disabling Cross Tool Deduplication does.

The fourth to seventh reviews' documentation items are in the docs commits (the seventh's is
the last commit: the Global Locations intro names the hub, and the em dashes on the Location Drift
Matching and About Deduplication pages are gone; every page this PR touches is now free of them): every deduplication page gives
the Finding Workflow path first with the previous menu's path in parentheses; the sidebar page
no longer lists the three retired tuner pages; the Global Component and Global Locations pages
describe the Matching Configuration procedure, say a pooled Asset is bounded to its pool, and no
longer claim an algorithm change recomputes hashes; the tuning page drops the Support-only and
Assets-only statements and explains that every tool's cross-tool cell starts as Disabled; the
pools page names the Dedupe Pool permissions the way the roles editor does and states the
designated-member rule and the age check; the changelog and overview count three global
algorithms and scope false-positive replication to same-tool matching.