Tooling: derive find_overlap task terms from research package roots

[commdata2338]

Change and mathematical scope

A tooling fix; no mathematical result, supplier or κ change.

The defect: scripts/find_overlap.py --task adds each research starting point's immediate parent folder as an OR search term. For nested files that folder is a generic word. The revision-4 joint-query-controller card searches for evidence (twice) and never for its package, joint-query; centre-path-sharing adds proofs. Generic hits can push a genuine lead below the default 20-result limit.

The fix: take the package component of repository-relative research/PACKAGE/... paths, so a nested file contributes its package; top-level research documents contribute no term. Explicit and catalogue overlap terms (generic words included), snapshot collection, scoring, --path matching and coverage reporting are unchanged. The other revision-4 cards derive the same term sets as before.

Effect on one fixed snapshot (403 open PRs and 810 Discussion records, plus this base's local records): --task joint-query-controller goes from 1,487 possible matches to 33, and --task centre-path-sharing from 386 to 261. The removed matches came only from the generic terms; every match to a retained term remains. These counts illustrate the defect; they are not test assertions or a novelty guarantee.

Remaining: literal substring search is still heuristic, so this does not make overlap detection complete. Windows execution and hosted CI were not run.

Task and overlap

• Task ID / scope: overlap-receipt (lookup key 5ae821d1b52092164092), changed to find_overlap/task-derived-terms/nested-research-package-roots. Chooser nonce 062c8d19991bc9ca650f6c96f1b1d3b6, track bit-mechanisms, priority revision 4; its suggestions (bit-helper-contract, bit-new-register-model) overlap this account's completed work, and the central handoffs considered were already claimed. The defect showed up while running overlap checks for those handoffs. No reroll.
• Base and head: base 0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2, rechecked unchanged at 21:12 UTC; contribution 5984d9999bceaeb7d1ce9a3f4edfbfcd0b70c118. No pending dependency. Nick Petalas's earlier pagination repair (9c2fdd89e553751e40ef8011716a249e8385d284) is retained unchanged.
• Scope status: changed, from an overlap-receipt investigation to a demonstrated coordination-tool defect that hides leads on a central card. It supports task coordination; it is not mathematical progress.
• Nearest work: the existing pagination, Unicode and path-index tests (including PR test: make the CP1252 overlap regression self-contained #1702's fixture) cover other helper behaviour. The changed-file index and a live check of newer PRs show no open PR touching scripts/find_overlap.py.
• Claim: discussion #1200.

Validation

python3 -B -m unittest discover -s tests -p 'test_research_overlap_terms.py'
python3 -B -m unittest discover -s tests -p 'test_research_*.py'
git diff --check

Linux x86_64, CPython 3.12.3. The four new CLI regression groups (a lead displaced below the default limit, exclusively nested packages, explicit generic terms and --all-terms preserved, catalogue terms not treated as stopwords) use isolated offline snapshots and check that the cache bytes and coverage metadata are unchanged.

• All four fail when run against the current helper on main, and pass with the fix.
• The full research-workflow suite passes: 69 tests in about 6 seconds, rerun before submission under an 8 GiB memory cap. The suite's intentional failing-subprocess fixtures print tracebacks; those are passing negative controls.

Credit

Douglas Colkitt and the contributors to the overlap helper and its tests, including Nick Petalas's pagination repair. Apache-2.0.

AI assistance: submitted by @commdata2338 with substantial AI assistance. OpenAI Codex (GPT-6 Astra) found the defect and wrote the fix, the tests and the evidence; it was packaged and submitted with Claude Code. No independent human review is claimed.

Open next questions

None justified beyond this fix. A broader change to ranking would need its own relevance fixtures and overlap check.

Workflow feedback (optional)

• Friction: the chooser's draw was lost to display truncation and recovered from the session log. Saving its JSON before rendering, for example with an --output path as suggested in PR Scoped proof: PR1918's selected centre-source minor lifts to native rank 8192 (no new kappa) #2048, would keep the first draw durable.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X86sCSXdoDd61SDFfC1PKG