feat(hints): v4 success-path find road signs (F1–F3)

[HumanBean17]

Summary

• Add F1–F3 find success-path hints in mcp_hints.py: route → inbound EXPOSES, client → outbound HTTP_CALLS, producer → outbound ASYNC_CALLS.
• Page-full gate: F-rows suppressed when len(results) >= limit and has_more_results is true; page-full meta stays PRIORITY_META, success rows at PRIORITY_LEAF_FOLLOWUP.
• When multiple matches, {id} is results[0]["id"] only (output-level sign, not per-row).
• Appendix traceability paragraph in propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md for v4 second partial dot-key reversal (neighbors success path).
• S1 (search single-hit → describe) not shipped — deferred per plan default.

Implements PR-B from plans/PLAN-HINTS-V4.md / propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md (issue #163).

No re-index. Query-time hint logic only.

Test plan

• .venv/bin/ruff check .
• .venv/bin/python -m pytest tests/test_mcp_hints.py -v -k "hints_find_route_success or hints_find_client or hints_find_producer or hints_find_success"
• .venv/bin/python -m pytest tests -v (637 passed; use .venv/bin on PATH for CLI tests)
• Sentinel: no ONTOLOGY_VERSION, build_ast_graph.py, or neighbors success trigger changes

Made with Cursor

[HumanBean17]

Review (approve with minor nits)

Solid, plan-faithful PR-B: F1–F3 wired correctly, page-full gate + _find_is_page_full refactor look good, sentinels clean, S1 deferral documented. Local test_mcp_hints.py is green.

Strengths

• Correct gates: success, non-empty results, not page-full (has_more_results), kind ∈ {route, client, producer}, results[0].id, 120-char cap.
• Priority: page-full PRIORITY_META (1), F-rows PRIORITY_LEAF_FOLLOWUP (2); suppression when page-full is tested.
• Traversals align with describe/neighbors v4 (route → EXPOSES in, client → HTTP_CALLS out, producer → ASYNC_CALLS out).
• Good extras: multi-match uses first id only (tested), templates in char-cap parametrize.

Suggestions (non-blocking)

1. find_v2 round-trip — PR-A required a neighbors_v2 integration test; this PR only exercises generate_hints("find", synthetic_payload). One cheap kuzu_graph test would close the loop, e.g. find_v2("route", …) and assert TPL_FIND_SUCCESS_HANDLER with out.results[0].id.

2. Locked catalog drift — HINTS-ROAD-SIGNS-PROPOSE.md UC12 still says successful find emits no hints; v4 now emits F1–F3 for route/client/producer. The appendix paragraph documents neighbors dot-keys (PR-A traceability per plan) but not find success. Consider a short v4 find amendment or Appendix A rows + UC12 update (can be follow-up).

3. Optional negatives — kind="symbol" with results → no F-row; missing results[0].id → silent.

4. Post-merge hygiene — per plan, move propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md and plans/PLAN-HINTS-V4.md to completed/ when the full v4 effort lands.

results[0] only on multi-match is an accepted v4 limitation (Open Q4) — fine as long as it stays in the PR description.

LGTM once CI is green.