add trace hints and skill integration (PR-TRACE-3)

[HumanBean17]

Summary

• Extend generate_hints with output_kind="trace" supporting four hint templates: budget hit, pruned drilldown, cross-service boundary, and high fanout trace recommendation
• Add trace recommendation to neighbors/describe high-fanout hint paths (when CALLS ≥ 10)
• Update skills/explore-codebase/SKILL.md with trace Q-class, four new decision tree rows, and trace tool reference section
• Add "trace" to StructuredHint.tool Literal in mcp_v2.py (one-line fix required for trace hints to flow through the hint → output pipeline)

Changes

File	Change
mcp_hints.py	New _trace_structured_hints() with budget hit, pruned drilldown, cross-service boundary, and high fanout trace hints. New labels: LABEL_BUDGET_HIT, LABEL_PRUNED_DRILLDOWN, LABEL_CROSS_SERVICE_BOUNDARY, LABEL_HIGH_FANOUT_TRACE. Trace recommendation added to neighbors and describe high-fanout paths.
mcp_v2.py	Add "trace" to StructuredHint.tool Literal (line 181)
skills/explore-codebase/SKILL.md	Updated preamble (trace Q-class), 4 new decision tree rows, trace tool reference section
tests/test_mcp_hints.py	4 new tests: test_hint_trace_budget_hit, test_hint_trace_pruned_edges, test_hint_trace_cross_service_boundary, test_hint_neighbors_high_fanout_mentions_trace
tests/test_mcp_trace.py	1 new integration test: test_trace_bank_chat_cross_service_http_flow

Test plan

• 5 new tests pass (tests/test_mcp_hints.py + tests/test_mcp_trace.py)
• .venv/bin/ruff check . clean
• .venv/bin/python -m pytest tests -v green (647 passed, 8 skipped)
• No changes to mcp_trace.py, kuzu_queries.py, server.py, build_ast_graph.py
• git diff experimental -- mcp_trace.py is empty

🤖 Generated with Claude Code

[HumanBean17]

Review: PR-TRACE-3 — trace hints and skill integration

Overall this is clean and well-tested. Approve with a few minor suggestions:

What looks good

• _trace_structured_hints() mirrors existing patterns, three cases are logically distinct and well-ordered.
• xs_edges[:3] cap prevents hint spam on many cross-service edges.
• mcp_v2.py change is exactly one token. No drift.
• SKILL.md additions (4 decision-tree rows, trace reference section, Q-class update) are thorough.
• Tests are well-scoped: 4 unit + 1 integration.

Suggestions (non-blocking)

1. Duplicate high-fanout trace hint in neighbors and describe paths
The _StructuredHint("trace", ...) block at ~L762 (neighbors) and ~L1011 (describe) is identical — same args, label, reason string. Extracting a _high_fanout_trace_hint(origin_id, calls_n) helper would prevent future drift.

2. prune_roles hardcoded in budget-hit hint
The budget-hit hint always suggests ["DTO", "EXCEPTION", "UTILITY"]. If the user already passed custom prune_roles, this overrides their choice. Consider:

"prune_roles": list(payload.get("prune_roles") or ["DTO", "EXCEPTION", "UTILITY"]),

3. Cross-service advisory references from_id but the structured hint only carries to_id
Acting on the hint alone loses origin context. Consider adding from_id to the hint args or reason.

4. stats guard silently drops all hints
If success=True but stats is missing/malformed, zero hints are produced — even cross-service boundary hints that don't strictly need stats. Worth a comment or a split guard.

5. Integration test fan_out_cap=0
test_trace_bank_chat_cross_service_http_flow passes fan_out_cap=0. If this means "no cap," a brief comment would clarify intent.