plan: resolve tool (PR-RESOLVE-1 → PR-RESOLVE-2)

[HumanBean17]

Summary

• Adds plans/PLAN-RESOLVE-TOOL.md — execution plan for the fifth MCP tool resolve, implementing propose/RESOLVE-TOOL-PROPOSE.md.
• Adds plans/CURSOR-PROMPTS-RESOLVE-TOOL.md — per-PR Cursor handoff prompts.

Landing order: PR-RESOLVE-1 (tool + tests) → PR-RESOLVE-2 (agent-facing description sweep). No ontology bump / no reindex.

Test plan

• Plan-only change — test suite not run (docs/planning PR).
• Review plan against propose §3–§7 for scope alignment.
• After merge, implement PR-RESOLVE-1 using CURSOR-PROMPTS-RESOLVE-TOOL.md.

Made with Cursor

[HumanBean17]

PR #135 review — plan: resolve tool

Verdict: Approve (plan-only). Solid, implementation-ready plan pair that tracks propose/RESOLVE-TOOL-PROPOSE.md closely and matches the repo’s established plan + Cursor-prompt pattern (e.g. plans/completed/PLAN-MCP-FILTER-FRAME.md).

---

What’s good

Propose alignment (§3–§7)
The two-PR split, landing order, and scope boundaries match the propose:

Propose topic	Plan coverage
ResolveReason closed set (§3.4)	java_ontology.py snippet + test 16
Output invariants / malformed vs none (§3.2, §7.11–16)	_resolve_assert_invariants, tests 5–7, 17
Ranking + dedupe + K=10 (§3.5–3.6)	Helpers table, tests 3–4, 9
PR-RESOLVE-2 sweep checklist (§6)	File-by-file + sentinel grep
No ontology bump	Stated in principles, DoD, prompts

Fixture assumptions are real
kuzu_db_path_fqn_collision_smoke already exists in tests/conftest.py; tests/fixtures/fqn_collision_smoke/ has com.example.SharedDto in two services — exactly what UC3 / test 3 need. Adding kuzu_graph_fqn_collision_smoke mirrors kuzu_graph_route_extraction_smoke.

Sensible interim agent surface
PR-RESOLVE-1 ships a complete resolve tool description while keeping pre-resolve fallback on search/describe until PR-RESOLVE-2. That matches propose decision §7.15 and current server.py wording.

Implementer guardrails
Out-of-scope lists, sentinel greps, binding test names (17 + 2), explicit “plan wins” hierarchy, and the _resolve_node_kind vs resolve_v2 naming note are appropriate for agent handoff.

Test design
FakeGraph for dedupe (test 9) and optional cross-kind stub (test 8) follow existing test_describe_by_fqn_duplicate_* patterns. Looseness on bank-chat (one or many for clients/routes) matches tests/README.md philosophy.

---

Suggestions (non-blocking)

1. Propose status — Propose header is still draft; plan is active (planning). When #135 merges, flip propose to active (or “locked”) so implementers don’t treat it as tentative.

2. PR-RESOLVE-2 doc surface is slightly narrow — Sweep covers server.py, mcp_v2 hint, docs/AGENT-GUIDE.md, README.md. These still say four tools and will be stale after RESOLVE-2:

   • AGENTS.md
   • .cursor/rules/project-overview.mdc
   • docs/JAVA-CODEBASE-RAG-CLI.md
   • docs/skills/java-codebase-explore.md

   AGENT-GUIDE also has “Tool reference — four tools”; plan mentions “five tools” but not renaming that heading — worth one explicit bullet in PR-RESOLVE-2.

   Either extend PR-RESOLVE-2 file list or add an optional follow-up chore.

3. Unify sentinel grep strings — CURSOR-PROMPTS uses per.candidate|until.*resolve|promising candidates; PLAN uses per.candidate|until.*resolve|search\(query=.*\).*describe. Pick one canonical pattern (plan’s version is stricter).

4. PR-RESOLVE-2 test rename — Plan/prompt allow rename or keep name + update assertions. Prefer a single binding name: test_describe_by_fqn_duplicate_hint_points_to_resolve.

5. PR-RESOLVE-1 manual spot-check — The python -c block in CURSOR-PROMPTS is incomplete; delete or replace with a concrete one-liner (e.g. collision fixture resolve_v2).

6. test_resolve_exact_id_symbol_returns_one — Test 1 allows one without reason=="exact_id"; fine if test 16 is strict across VALID_RESOLVE_REASONS.

7. PR-RESOLVE-1 _INSTRUCTIONS — After PR-1, _INSTRUCTIONS should list five tools (even if sibling descriptions still mention the old fallback) so the MCP host isn’t told there are only four while resolve is registered.

---

Risks already handled well

• Out-of-order merge — blocked PR-RESOLVE-2, cross-PR risks table
• NL / wildcard inputs — tests 14–15
• Generator overlap — test 9 + dedupe spec
• Namespace collision — explicit no-rename of _resolve_node_kind

---

Bottom line: Safe to merge as the execution blueprint for RESOLVE-1 → RESOLVE-2. Main follow-up: decide whether PR-RESOLVE-2 should include AGENTS.md / rules / skill (or a tracked chore) so post-merge docs don’t contradict README.