propose: trace tool — multi-hop navigation shortcut

[HumanBean17]

Summary

• Proposes a trace MCP tool that does multi-hop BFS server-side in one call
• Addresses agent drowning during neighbors loops — the AST by Opus #1 usability problem on real codebases
• Preserves the GPS metaphor: returns paths/structure, not answers; agent still interprets results

Key design decisions

• Three pruning mechanisms the agent can't replicate manually: prune_roles, fan_out_cap, collapse_trivial
• Cross-service seamless traversal — follows HTTP_CALLS/ASYNC_CALLS through Client/Producer → Route in one call
• Required direction + edge_types — same discipline as neighbors
• Additive — existing 5 tools unchanged; neighbors loops still work for agents that prefer them

Scope

• Proposal only — no code changes in this PR
• 4 PRs outlined for implementation if accepted
• No ontology bump, no re-index, no schema changes

Relationship to v2 design

The v2 proposal locked "no trace tools." Appendix A provides point-by-point justification for revisiting this decision based on production evidence. The rejected v1 trace_flow was a role waterfall encoding intent; this trace is a generic BFS shortcut batching mechanics.

Open questions (6)

See the proposal's "Open Questions" section — particularly #3 (bidirectional), #5 (memory budget), and #6 (legacy method coexistence).

🤖 Generated with Claude Code

Refs #232