address PR-176 review: find round-trip, docs, landing hygiene

Add find_v2 kuzu_graph round-trip and negative gates; update
HINTS-ROAD-SIGNS catalog/UCs for v4 find success; move v4 propose
and plan to completed/.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

mcp_hints.py

@@ -4,7 +4,7 @@
 (issue #161 producer/override-route amendments in that appendix).
 v2 resolve + neighbors fuzzy-strategy catalog: ``propose/completed/HINTS-V2-PROPOSE.md`` Appendix A.
 v3 empty-neighbors structural catalog: ``propose/completed/HINTS-V3-PROPOSE.md`` §3.1–3.3.
-v4 non-empty neighbors success-path catalog: ``propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md``.
+v4 success-path catalog: ``propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md``.
 Priority cap: same propose §7.12 / ``plans/completed/PLAN-HINTS.md`` principles.
 """
 

plans/CURSOR-PROMPTS-HINTS-V4.md …ans/completed/CURSOR-PROMPTS-HINTS-V4.mdplans/CURSOR-PROMPTS-HINTS-V4.md renamed to plans/completed/CURSOR-PROMPTS-HINTS-V4.md plans/CURSOR-PROMPTS-HINTS-V4.md renamed to plans/completed/CURSOR-PROMPTS-HINTS-V4.md

@@ -1,7 +1,7 @@
 # Plan: HINTS-V4 (success-path road signs)
 
-Status: **active (PR-A in progress)**. This plan implements
-[`propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md`](../propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md)
+Status: **completed** (PR-A [#175](https://github.com/HumanBean17/java-codebase-rag/pull/175), PR-B [#176](https://github.com/HumanBean17/java-codebase-rag/pull/176)). This plan implements
+[`propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md`](../propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md)
 (issue [#163](https://github.com/HumanBean17/java-codebase-rag/issues/163)).
 
 Depends on: **NEIGHBORS-DOT-KEY-TRAVERSAL** landed ([#171](https://github.com/HumanBean17/java-codebase-rag/pull/171);
@@ -178,10 +178,10 @@ Implement **verbatim** names from the propose:
 
 ## Definition of done (PR-B)
 
-- [ ] F1–F3 wired; page-full + empty-resolve behavior unchanged.
-- [ ] Named find tests pass; optional S1 test if implemented.
-- [ ] Appendix paragraph added to `HINTS-ROAD-SIGNS-PROPOSE.md`.
-- [ ] Full test suite green; no ontology/README requirement unless reviewer asks for README mention.
+- [x] F1–F3 wired; page-full + empty-resolve behavior unchanged.
+- [x] Named find tests pass; optional S1 test if implemented (S1 deferred).
+- [x] Appendix paragraph added to `HINTS-ROAD-SIGNS-PROPOSE.md`.
+- [x] Full test suite green; no ontology/README requirement unless reviewer asks for README mention.
 
 ## Implementation step list
 
@@ -227,9 +227,9 @@ Implement **verbatim** names from the propose:
 
 # Tracking
 
-- `PR-A`: _landed (PR open)_
-- `PR-B`: _pending_
+- `PR-A`: _landed ([#175](https://github.com/HumanBean17/java-codebase-rag/pull/175))_
+- `PR-B`: _landed ([#176](https://github.com/HumanBean17/java-codebase-rag/pull/176))_
 
 ## Cursor handoff
 
-[`plans/CURSOR-PROMPTS-HINTS-V4.md`](./CURSOR-PROMPTS-HINTS-V4.md)
+[`plans/completed/CURSOR-PROMPTS-HINTS-V4.md`](./CURSOR-PROMPTS-HINTS-V4.md)

plans/PLAN-HINTS-V4.md plans/completed/PLAN-HINTS-V4.mdplans/PLAN-HINTS-V4.md renamed to plans/completed/PLAN-HINTS-V4.md

@@ -108,6 +108,9 @@ The full catalog of hints emitted at v1. Each row is one template; multiple may
 | `describe` (client node) | always | `declaring method: neighbors([{id}],'in',['DECLARES_CLIENT'])` |
 | `find` | `len(results) == 0` and filter has an identifier-shaped value (e.g. `fqn_prefix`, `target_service`) | `no matches — try resolve(identifier, hint_kind='{kind}') for canonical lookup` |
 | `find` | `len(results) >= limit` (page-full) | `result page full at {limit} — narrow filter or paginate` |
+| `find` (route) | `len(results) > 0`, not page-full | `handler: neighbors(['{id}'],'in',['EXPOSES'])` — `{id}` = `results[0].id` (#163 v4) |
+| `find` (client) | same, `kind == client` | `HTTP targets: neighbors(['{id}'],'out',['HTTP_CALLS'])` (#163 v4) |
+| `find` (producer) | same, `kind == producer` | `async targets: neighbors(['{id}'],'out',['ASYNC_CALLS'])` (#163 v4) |
 | `neighbors` | `len(results) == 0` and `len(edge_types) > 0` | `0 results — check if the requested edge_types apply to this kind` |
 | `neighbors` | rows include `edge_type='DECLARES'` to method targets, **and** any of those methods has known `DECLARES_CLIENT` out in summary | (deferred — needs second-hop awareness; not in v1) |
 | `search` | `len(results) == limit` **and** `(max_score - min_score) < 0.1 * max_score` (structural low-confidence signal — no absolute threshold). Requires `SearchOutput.limit` echo per §3.1 / §7.18. | `results look weak — narrow the query or try find(role=…)` |
@@ -138,8 +141,9 @@ This catalog is the v1 lock. Adding a new template requires a propose-doc amendm
 | UC9 | Agent does `neighbors([class_id], 'out', ['DECLARES_CLIENT'])` and gets 0 (correctly, because DECLARES_CLIENT lives on methods) | neighbors | "0 results — check if the requested edge_types apply to this kind" |
 | UC10 | Agent does `search`, gets a full page of hits all clustered within 10% of the top score (no dominant match) | search | "results look weak — narrow the query or try find(role=…)" |
 | UC11 | Agent describes a leaf method (no rollups, no override axis) | describe | (no hints — clean output, agent has all it needs) |
-| UC12 | Agent does `find` with successful match list | find | (no hints — page not full, results present) |
-| UC13 | Agent does `neighbors` with results matching all requested edge_types | neighbors | (no hints — happy path) |
+| UC12 | Agent does `find` on route, client, or producer with successful match list, not page-full | find | v4 success follow-up (F1–F3): handler / HTTP targets / async targets using `results[0].id` |
+| UC12b | Agent does `find(kind=symbol)` with successful match list | find | (no v4 find hints — symbol kind out of F1–F3 scope) |
+| UC13 | Agent does `neighbors` with homogeneous results at `offset==0`, single edge type | neighbors | v4 success follow-ups (N1a–N7) when triggers match; else fuzzy-strategy meta only |
 | UC14 | Agent describes a class with `DECLARES.DECLARES_CLIENT` and `DECLARES.EXPOSES` both non-zero, plus `OVERRIDDEN_BY` (it's an interface) | describe | up to 3 hints — clients via members, routes via members, overriders if applicable |
 
 15 realistic cases (UC6a + UC6b counted separately). The §2.5 cap is exercised by a dedicated test scenario in §6 (a hand-crafted record with > 5 firing conditions), not by a hypothetical UC — the UC re-walk is the design-validation move, the cap is a guardrail with its own test.
@@ -266,6 +270,9 @@ kind == producer, always        →  "declaring method: neighbors(['{id}'],'in',
 # FindOutput
 results==[] and filter has identifier-shaped value  →  "no matches — try resolve(identifier, hint_kind='{kind}') for canonical lookup"
 len(results) >= limit                               →  "result page full at {limit} — narrow filter or paginate"
+kind==route, len(results)>0, not page-full          →  "handler: neighbors(['{id}'],'in',['EXPOSES'])"  # v4 #163
+kind==client, len(results)>0, not page-full         →  "HTTP targets: neighbors(['{id}'],'out',['HTTP_CALLS'])"  # v4 #163
+kind==producer, len(results)>0, not page-full       →  "async targets: neighbors(['{id}'],'out',['ASYNC_CALLS'])"  # v4 #163
 
 # NeighborsOutput
 results==[] and edge_types non-empty  →  "0 results — check if the requested edge_types apply to this kind"
@@ -280,7 +287,7 @@ File placement (`mcp_hints.py`), function decomposition, integration points in `
 
 **Amendment (2026-05-16, issue #161 / PR #164)** — five describe templates for the producer axis and override-route rollup, symmetric with the client/route rows above: `DECLARES.DECLARES_PRODUCER`, `DECLARES_PRODUCER`, `OVERRIDDEN_BY.DECLARES_PRODUCER`, `OVERRIDDEN_BY.EXPOSES`, and `kind == producer` declaring-method hint. No ontology or re-index change.
 
-**Amendment (v4 success-path, issue #163)** — second partial dot-key emission reversal: non-empty `neighbors` success hints on type Symbol origins may recommend `DECLARES.DECLARES_CLIENT`, `DECLARES.DECLARES_PRODUCER`, and `DECLARES.EXPOSES` (matching describe rollups). v3 empty structural `neighbors` hints still never use dot-keys (`_filter_neighbors_dotkey_hints` applies to the empty branch only). `OVERRIDDEN_BY.*` dot-keys remain describe-only. No ontology or re-index change.
+**Amendment (v4 success-path, issue #163)** — (1) **Find:** non-page-full `find` on route/client/producer emits F1–F3 (`handler` / `HTTP targets` / `async targets`); `{id}` = `results[0].id` when multiple matches. (2) **Neighbors — second partial dot-key emission reversal:** non-empty success hints on type Symbol origins may recommend `DECLARES.DECLARES_CLIENT`, `DECLARES.DECLARES_PRODUCER`, and `DECLARES.EXPOSES` (matching describe rollups). v3 empty structural `neighbors` hints still never use dot-keys (`_filter_neighbors_dotkey_hints` applies to the empty branch only). `OVERRIDDEN_BY.*` dot-keys remain describe-only. No ontology or re-index change.
 
 **What stayed unchanged from the first draft**
 

propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-**Status**: locked — not yet implemented. Tracks [issue #163](https://github.com/HumanBean17/java-codebase-rag/issues/163). Implementation plan: [`plans/PLAN-HINTS-V4.md`](../plans/PLAN-HINTS-V4.md) (planning PR [#174](https://github.com/HumanBean17/java-codebase-rag/pull/174)); Cursor prompts: [`plans/CURSOR-PROMPTS-HINTS-V4.md`](../plans/CURSOR-PROMPTS-HINTS-V4.md).
+**Status**: completed (landed PRs [#175](https://github.com/HumanBean17/java-codebase-rag/pull/175) neighbors, [#176](https://github.com/HumanBean17/java-codebase-rag/pull/176) find). Tracks [issue #163](https://github.com/HumanBean17/java-codebase-rag/issues/163). Plan: [`plans/completed/PLAN-HINTS-V4.md`](../plans/completed/PLAN-HINTS-V4.md); Cursor prompts: [`plans/completed/CURSOR-PROMPTS-HINTS-V4.md`](../plans/completed/CURSOR-PROMPTS-HINTS-V4.md).
 
 **Depends on (landed):** [NEIGHBORS-DOT-KEY-TRAVERSAL](./completed/NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md) ([#171](https://github.com/HumanBean17/java-codebase-rag/pull/171)) — `neighbors` accepts `DECLARES.DECLARES_CLIENT`, `DECLARES.DECLARES_PRODUCER`, `DECLARES.EXPOSES` on type Symbol origins; describe rollup templates already prescribe those dot-keys.
 

propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md …mpleted/HINTS-V4-SUCCESS-PATH-PROPOSE.mdpropose/HINTS-V4-SUCCESS-PATH-PROPOSE.md renamed to propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md renamed to propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md

@@ -1225,6 +1225,35 @@ def test_hints_find_success_uses_first_result_id_when_multiple() -> None:
     assert mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=second) not in hints
 
 
+def test_hints_find_symbol_success_emits_no_v4_followup() -> None:
+    sym_id = "sym:com.example.T"
+    payload = _find_success_payload("symbol", sym_id)
+    hints = generate_hints("find", payload)
+    v4_markers = (
+        mcp_hints.TPL_FIND_SUCCESS_HANDLER,
+        mcp_hints.TPL_FIND_SUCCESS_HTTP_TARGETS,
+        mcp_hints.TPL_FIND_SUCCESS_ASYNC_TARGETS,
+    )
+    assert not any(m.format(id=sym_id) in hints for m in v4_markers)
+
+
+def test_hints_find_success_silent_when_first_result_missing_id() -> None:
+    payload = _find_success_payload("route", "route:unused")
+    payload["results"] = [{"kind": "route"}]
+    hints = generate_hints("find", payload)
+    assert not any("handler:" in h and "EXPOSES" in h for h in hints)
+
+
+def test_hints_find_v2_route_success_emits_handler(kuzu_graph) -> None:
+    out = find_v2("route", {"path_prefix": "/api"}, graph=kuzu_graph, limit=500, offset=0)
+    assert out.success is True
+    assert out.results
+    rid = out.results[0].id
+    want = mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=rid)
+    assert want in out.hints
+    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=500) not in out.hints
+
+
 def test_hints_find_page_full_requires_has_more_results_flag() -> None:
     full_page = {
         "success": True,