feat(hints): kind- and direction-aware empty-result hints driven by EDGE_SCHEMA

[HumanBean17]

Summary

• Replaces TPL_NEIGHBORS_EMPTY_KIND_CHECK with four EDGE_SCHEMA-driven empty-result templates (WRONG_SUBJECT_KIND, WRONG_DIRECTION, TYPE_LEVEL_REQUERY, BROWNFIELD_RESOLVED_MAYBE_UNRESOLVED).
• Adds neighbors_empty_hints() / typical_traversal_for() in mcp_hints.py; wires empty neighbors branch in generate_hints.
• Extends neighbors_v2 hint payload with requested_direction, origin_id, and subject_record (first origin when batching).
• Query-time only — no re-index / no ontology_version bump.

Plan / propose

• plans/PLAN-HINTS-V3.md § PR-D
• propose/HINTS-V3-PROPOSE.md (Status: locked)

Test plan

.venv/bin/ruff check .
PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python -m pytest tests -v
.venv/bin/python -m pytest tests/test_mcp_hints.py -v -k "hints_hv or neighbors"

• HV1–HV20 + integration test_hints_neighbors_v2_empty_post_flip_method_http_calls
• v2 fuzzy hint unchanged on non-empty neighbors (HV16 path; skipped when fixture lacks fuzzy Client HTTP_CALLS)
• Sentinel: no ONTOLOGY_VERSION, graph builder, or TPL_NEIGHBORS_EMPTY_KIND_CHECK changes

Manual evidence

test_hints_neighbors_v2_empty_post_flip_method_http_calls on session graph (post-flip Client→Route HTTP_CALLS): method subject + HTTP_CALLS out returns WRONG_SUBJECT_KIND with DECLARES_CLIENT traversal chain in hints.

Made with Cursor

[HumanBean17]

Review (PR-D / HINTS-V3)

Verdict: Approve — solid, plan-aligned delivery. Query-time only, EDGE_SCHEMA-driven evaluation order, and HV1–HV20 + post-flip integration test give good confidence. Assuming CI is green, this is fine to merge.

What works well

• Faithful to locked propose: alien kind → wrong direction → type-level requery; brownfield row 4 deduped once; v2 fuzzy path unchanged on non-empty results.
• Clean split: pure neighbors_empty_hints() / typical_traversal_for() in mcp_hints.py; mcp_v2 only enriches the hint payload.
• Post-flip method + HTTP_CALLS → WRONG_SUBJECT_KIND with member_subject traversal is the right teaching moment (integration test covers it).
• Dot-key post-filter + HV19 schema coverage are good guardrails.

Follow-ups (non-blocking)

1. Brownfield row 4 is broad — fires on any empty result when any requested edge is brownfield_resolver_sourced, including structurally valid queries (e.g. method + empty DECLARES_CLIENT / EXPOSES / CALLS). HV8/HV9 only assert no structural hints. Consider gating row 4 to Client/Producer/Route subjects or caller-side edges only if real MCP sessions get noisy.

2. Failed subject_record load — subject_record if subject_record is not None else {} makes {} look like Symbol with no kind, which can emit misleading structural hints. Safer to skip neighbors_empty_hints when load returns None.

3. Pagination / filter empty slice (pre-existing) — hints use sliced results; offset past rows or a strict filter can yield [] while hops exist. New hints are more specific, so misleading guidance is slightly worse than the old generic template. Worth a comment or offset == 0 guard in a follow-up.

4. Nits: origin_id in payload is unused by generate_hints; test_hints_hv1 asserts hints[0] (order-dependent); HV19 proves ∃ trigger per edge but not that every typical_traversals role key exists at runtime.

5. Process: after merge, move propose/HINTS-V3-PROPOSE.md → propose/completed/ per repo culture.

No re-index / ontology bump needed. Nice work on scope discipline.