fix: correct query/explain/path resolution failures on natural-language input

[nokternol]

Summary

query, explain, and path are designed to accept natural-language input, but several parts of the
resolution and ranking pipeline only worked correctly for short, exact identifier-style input. Multi-word
questions and phrases could silently resolve to the wrong node, an unrelated node, or no node at all, with
no indication that anything had gone wrong. This PR is a set of targeted fixes to that resolution pipeline —
seed selection, ranking, ambiguity handling, and fallback behavior — so that natural-language queries
against graph.json reliably reach the node(s) they describe, or fail visibly instead of silently.

Changes

Each change below targets a distinct, reproducible failure mode in how a natural-language query resolves to
graph nodes.

1. Guarantee per-term BFS seed diversity in query (_pick_seeds, graphify/serve.py)
_pick_seeds selected BFS seeds by combined score and discarded any candidate scoring below 20% of the top
score. On a multi-word query, one term's incidental exact match on an unrelated node (e.g. a common word
that also happens to be an identifier or field name elsewhere in the corpus) can outscore every other term's
weaker match by orders of magnitude, so the 20%-gap cutoff discarded every seed for the query's actually
relevant terms — the BFS then only ever explores the neighborhood of one unrelated node. Fix: guarantee at
least one seed per distinct query term that has any match at all, tie-broken by node degree. This does not
change single-term or already-unambiguous queries; it only recovers seeds that were previously discarded by
the gap cutoff.

2. Reattach cached semantic content on incremental AST-only rebuilds (_rebuild_code, graphify/watch.py)
The incremental code-only rebuild path evicts a re-extracted file's prior semantic nodes/edges
unconditionally and never regenerates them (no LLM call on that path by design), even when the semantic
cache already holds a valid, content-hash-matched result for the file's current bytes. Fix: check the
content-hash-keyed semantic cache for every re-extracted file before eviction and reattach any hit alongside
the fresh AST nodes. This adds no LLM cost (cache lookup only) and is byte-identical to a full rebuild's
cached output for files with a cache hit; files with no cache entry keep the existing AST-only behavior
unchanged.

3. Rank query output by relevance instead of raw degree (_subgraph_to_text, _query_graph_text,
graphify/serve.py)
_subgraph_to_text has always accepted a seeds parameter to render seed nodes first, but its only caller,
_query_graph_text, never passed it — every query result fell back to whole-graph degree-sort, so the
most-imported/highest-degree node in the corpus (test setup, DB schema, config, logger, etc.) led the output
regardless of relevance to the query, and the nodes the seeding logic actually selected could be pushed far
down or truncated out by the token budget. Fix: _query_graph_text now passes both seeds=start_nodes
(seeds render first) and scores=scored (the same per-node relevance scores already computed to select
seeds, now also used to rank the non-seed expansion). Nodes with no term overlap fall back to degree exactly
as before, so output ordering for a query with no scoring signal is unchanged.

4. Surface ambiguous or precedence-collapsed matches in explain instead of guessing (_find_node_tiers,
graphify/serve.py; graphify/__main__.py)
explain's single-node resolution already computed a full tier-ordered candidate list (exact
source-path match, exact match, prefix match, substring match) but took the first candidate unconditionally
and discarded the rest, with no signal when other candidates existed. Two related failure shapes: (a)
multiple candidates tied in the same top-precedence tier, and (b) exactly one top-tier candidate that is
weakly connected (degree ≤ 1), fully hiding a more relevant candidate one tier down purely due to tier
precedence. Fix: _find_node_tiers exposes tier boundaries so both shapes can be detected; explain now
lists all tied/hidden candidates instead of picking one, with a degree-dominance exception (top candidate's
degree at least ~3x the runner-up's resolves directly, since that is not a real ambiguity) and a --force
flag to bypass the guard and reproduce the prior single-candidate behavior.

5. Surface ambiguous endpoint matches in path instead of a warning that is ignored
(graphify/__main__.py)
path already computed a top-vs-runner-up score gap for each endpoint but only printed a stderr warning and
then silently proceeded with the top-scored candidate regardless. Fix: the same close-score-gap condition is
now a hard ambiguity gate — a numbered candidate list (label, source, degree, score) is shown instead of a
warning, with the same degree-dominance exception as (4) so a genuinely dominant symbol still resolves
directly, and the same --force flag to bypass.

6. Fall back to term-overlap candidates in explain instead of failing silently on a multi-word phrase
(graphify/__main__.py)
_find_node_tiers requires the query's tokens, rejoined into a single string, to match/prefix/substring a
single node's label as a whole. A genuine multi-word natural-language phrase (e.g. three or more words)
almost never appears as a literal substring of any one node's label, so this returns "No node matching
found" even when every individual word in the phrase exists on a real, relevant node — with no fallback and
no signal that anything went wrong. Fix: when the tiered lookup finds nothing and the phrase has more than
one token, fall back to the same per-token relevance scoring query already uses (_score_nodes) and list
the top candidates by term overlap, in the same candidate-list format used by (4). A genuine single-word
miss is unaffected — a one-word probe would score identically to the substring tier already tried and has
nothing new to find, so the fallback is gated on token count.

7. Gate _score_nodes' full-query bonus to multi-token queries (graphify/serve.py)
_score_nodes has a "joined" full-query tier so a multi-word query that equals or prefixes a whole
multi-word label wins outright, since no single token in a per-token score sum could otherwise equal that
label. This tier compares the query's tokenized form (punctuation stripped) against a node's tokenized
label. For a single-token query, this can falsely promote a node whose only word-character content matches
that one token — e.g. a bare method call like .search(), which tokenizes to "search" — to the same
tier as a genuine exact match, even though the same node correctly fails the ordinary per-token exact check
a few lines below (raw label ".search" is not equal to raw query "search"). This specifically affects
_pick_seeds's per-term seed-diversity check from (1), which probes each distinct query term in isolation
via _score_nodes(G, [term]): a short method name repeated across multiple unrelated files can win that
single-term probe outright and prevent a genuinely relevant multi-word file (which only reaches the prefix
tier for the same bare word) from ever being selected as a seed. Fix: gate the joined-tier bonus on
len(norm_terms) > 1. A single-token probe has no "multi-word phrase vs. per-token bag-of-words"
distinction to make — the per-token loop immediately below already fully and correctly handles single-term
exact/prefix/substring matching via raw, non-tokenized comparison. The combined multi-word query path used
everywhere else is unaffected, since it always has more than one token.

8. Cap explain's term-overlap fallback to avoid noise floods (graphify/__main__.py)
The fallback added in (6) has no floor on how broad a "match" is useful. A query whose only vocabulary
overlap with the corpus is one generic word (e.g. a word that is also a top-level directory name in the
codebase being queried) can match a large fraction of the entire graph at the weakest possible scoring tier,
and the fallback would present an arbitrary slice of that as though it were a considered answer, when in
fact none of the matched nodes are meaningfully distinguished from one another. Fix: after scoring, if the
candidate count exceeds both an absolute floor (50 — so small graphs are never affected) and 15% of the
graph's total node count, the fallback is treated as a noise flood and the plain zero-match message is shown
instead of a misleadingly specific candidate list. Genuine large-but-real candidate lists stay well under
this threshold and are unaffected.

Testing

Full test suite: 2768 passing, 28 skipped, 1 pre-existing failure unrelated to these changes
(tests/test_cache.py::test_semantic_prune_removes_orphan_entries, a test-order-dependent flake reproducible
identically on v8 before any commit in this PR). ruff check passes with no findings.

Each change above has dedicated regression tests in tests/test_serve.py, tests/test_watch.py,
tests/test_explain_cli.py, and tests/test_path_cli.py, covering both the failure case being fixed and a
non-regression pin for the prior, still-correct behavior it must not disturb.