feat(hints): describe structural hints — IMPLEMENTS/INJECTS wiring + method road signs

[HumanBean17]

Summary

• Adds 10 new describe success-path hint rows (A–E, G–J) reading edge_summary in/out counts and record.data — no graph re-query, no ontology bump, no re-index.
• Tier-1 structural hints (A–D: implementors, implements, dependencies, injectors) fire only when no type-rollup hints would emit (suppression invariant).
• Tier-2 method hints (E: outbound calls, G: super declaration, H: unresolved call sites) and client/producer second hops (I: HTTP targets, J: async targets) with per-row gates.
• Every new row has both string and _StructuredHint dual-list parity.
• Adds _in_count and _type_rollup_would_emit helpers; refactors is_type block from early-return to fallthrough with suppression gate.

Scope

• mcp_hints.py — helpers, 7 new TPL_DESCRIBE_* constants, control-flow refactor, all 10 rows with dual-list emission
• tests/test_mcp_hints.py — 21 new tests (12 string + 9 structured), regression relaxations, char-cap parametrization
• propose/DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md → propose/completed/

No ontology bump. No re-index. No changes to build_ast_graph.py, java_ontology.py, mcp_v2.py, server.py.

Plan + propose

• Plan: plans/PLAN-DESCRIBE-HINTS-STRUCTURAL.md § PR-1
• Propose: propose/completed/DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md

Manual evidence

.venv/bin/ruff check mcp_hints.py tests/test_mcp_hints.py
# All checks passed

.venv/bin/python -m pytest tests/test_mcp_hints.py -v -k describe
# 49 passed, 1 skipped, 169 deselected

.venv/bin/python -m pytest tests -v
# 759 passed, 10 skipped, 1 failed (pre-existing test_run_search_capability_filter_finds_row)

git diff master..HEAD -- build_ast_graph.py java_ontology.py mcp_v2.py server.py
# (zero output — sentinel check passes)

🤖 Generated with Claude Code

[HumanBean17]

Code Review

Overall this is a well-scoped, well-tested PR. The suppression invariant, dual-list parity, and fixture-aware test helpers are all solid. A few items worth considering:

1. Over-complicated override_axis_emits — mcp_hints.py:1205-1208

The list comprehension rebuilds the full OVERRIDDEN_BY + OVERRIDDEN_BY.* key set, but since OVERRIDDEN_BY.* sub-keys can only have out > 0 when OVERRIDDEN_BY itself has out > 0, the simpler form would suffice:

override_axis_emits = _out_count(edge_summary, "OVERRIDDEN_BY") > 0

The full key scan is redundant — any OVERRIDDEN_BY.DECLARES_CLIENT / .DECLARES_PRODUCER / .EXPOSES edges imply OVERRIDDEN_BY out > 0.

2. Method role extraction repeated — lines 1131 and 1197

Both use (rec.get("data") or {}).get("role") or rec.get("role") or "". A small helper like _record_role(rec) would deduplicate this and make the fallback logic explicit in one place.

3. Long line — mcp_hints.py:1131

The SERVICE-role guard is ~145 chars. Even if ruff passes with the project limit, extracting the role check (as in #2 above) would improve readability.

4. Duplicate char-cap test

test_hints_describe_structural_templates_char_cap re-checks the same 7 templates that were already added to the test_hints_all_v4_templates_under_120_chars parametrize list on line ~1093. The standalone test can be removed since the parametrize already covers them.

None of these are blockers — just cleanups that would tighten the diff. Good work on the suppression invariant test and the graceful pytest.skip fixture finders.