plan: hints v4 success-path road signs

[HumanBean17]

Summary

• Lock propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md for implementation (issue hints: expand success-path hint catalog — most tool invocations return empty hints #163).
• Add execution plan plans/PLAN-HINTS-V4.md: two PRs (PR-A neighbors N1a–N7, PR-B find F1–F3 + optional S1 + appendix).
• Add Cursor handoff plans/CURSOR-PROMPTS-HINTS-V4.md.

Depends on NEIGHBORS-DOT-KEY (#171, landed). No ontology bump or re-index — query-time mcp_hints.py only.

Test plan

• Docs/planning only — no code changes; no pytest run required.

Made with Cursor

[HumanBean17]

Summary

Solid planning PR: the two-PR split (neighbors → find), dot-key filter split, HV20 scope change, risk table, and sentinel grep contracts match repo conventions (PLAN-HINTS-V3, NEIGHBORS-DOT-KEY). Dependency on #171 is satisfied.

Please fix before merge one spec bug that would silently break production if implemented literally, plus a few doc hygiene items before PR-A.

---

Blocker: subject_record shape (propose + plan vs neighbors_v2)

The locked propose and PR-A plan gate N1a/N1b on NodeRecord semantics:

• subject_record["kind"] == "symbol"
• subject_record["data"]["kind"] in type declaration kinds

Production neighbors_v2 does not pass NodeRecord.model_dump() — it passes the raw Kuzu row from _load_node_record (mcp_v2.py ~1462–1470). That row uses top-level kind: "class" | "method" | …, same as v3 empty hints and tests/test_mcp_hints.py synthetic subjects ({"id": "sym:type", "kind": "class"}).

v3 empty hints already use the flat shape (subject_record.get("kind") in _TYPE_SYMBOL_KINDS in neighbors_empty_hints). Describe is the outlier (record.model_dump() with nested data).

Impact: PR-A implementer following the plan’s _type_subject_record(..., kind="symbol", data={...}) + NodeRecord gate will get green unit tests and no N1a/N1b in real neighbors_v2 output — the main #163 workflow.

Fix (docs only in this PR):

1. Amend propose § Payload / trigger §5 and plan PR-A helper text to match v3: type subject ⇔ _subject_node_label(subject_record) == "Symbol" and str(subject_record.get("kind") or "") in _TYPE_SYMBOL_KINDS (or reuse _symbol_declaration_kind with top-level fallback for flat rows).
2. Change test guidance: extend _neighbors_hint_payload / add _type_subject_record using flat Kuzu row, not NodeRecord.model_dump().
3. Require one neighbors_v2 round-trip test for N1a (plan already lists as optional — make it required given this footgun).

---

Should fix (same PR or immediate follow-up)

1. Stale propose § Sequencing (lines 248–249): still says plan + prompts are optional (“if the team wants…”). This PR adds them — update to “landed in planning PR #174” / remove the conditional.

2. CURSOR-PROMPTS lock line: says “Set Status: locked before opening PR-A” but this PR already locks the propose. Align with plan (“locked before PR-A merge”) or note lock is done in #174.

3. Propose test table gaps vs plan: plan adds test_hints_neighbors_async_calls_in_producers_emits_declares_producer (N6) and test_hints_find_producer_success_emits_async_calls (F3); propose § Tests omits both. Sync the locked propose table so PR-B isn’t argued as out-of-scope.

4. Multi-origin neighbors: v3 documents origins[0] for hints. v4 is silent. Worth one line: success hints use echoed origin_id / first origin only; no v4 hints when len(origins) > 1 (or explicitly allow — but document).

5. Homogeneity edge case: plan says “mixed method vs type Symbols” → silence; clarify whether method + constructor on one page is homogeneous (recommend: yes, both ∈ _METHOD_SYMBOL_KINDS).

---

Nits (non-blocking)

• Propose status uses prose **locked** vs other proposes’ Status: locked — minor consistency.
• N1a/N1b always co-fire (lossy) is well called out; PR-A body reminder is enough.
• S1 deferral to optional PR-B is reasonable; keeping it behind reviewer approval in the prompt is good.

---

What looks good

• Dot-key filter split (_filter_neighbors_dotkey_hints on empty branch only) directly addresses current generate_hints behavior (filters all pairs today — line 415).
• HV20 narrowing + test_hints_neighbors_success_may_emit_declares_dot_keys is the right regression pair.
• Priority / cap story (success @ 2 vs fuzzy/empty @ 1) matches finalize_hint_list semantics.
• No ontology / no mcp_v2 scope is correct post-#171.
• Cross-PR risks table (#1, #7) is accurate against the codebase.

Docs-only PR — no pytest required here. Please fix the subject_record contract before merge so PR-A doesn’t ship a green-but-dead success path.

[HumanBean17]

Re-review (post follow-up commit)

All items from the first review are addressed in 5a1e0c6:

Prior issue	Resolution
Blocker: subject_record NodeRecord vs flat Kuzu row	Propose amendment table, payload §, trigger §5, plan principles + PR-A helper + CURSOR-PROMPTS all specify v3 flat gate (_subject_node_label + top-level kind in _TYPE_SYMBOL_KINDS).
Stale sequencing §	Updated to reference planning PR #174 and plans/completed/ move.
CURSOR-PROMPTS lock wording	Aligned: locked in #174, must stay locked before PR-A merge.
Missing N6 / F3 tests in propose table	Added with plan parity.
Multi-origin	Trigger §6 + plan principle (origins[0] parity).
method + constructor homogeneity	Trigger §3 + plan principle + CURSOR-PROMPTS.
Optional round-trip → required	test_hints_neighbors_v2_declares_success_emits_dot_key_clients in propose, plan DoD, risk #2, implementation step 5.

Verdict: LGTM — ready to merge. Planning artifacts are implementation-ready; PR-A can proceed off master (#171 landed).

Nit (optional): propose ## Status body repeats the word Status (**Status**: locked). Could simplify to locked — not yet implemented under the heading when you next touch the file.