implement trace tool v2: tree output, bidirectional traversal

[HumanBean17]

Summary

Implements PLAN-TRACE-TOOL-V2 as a single PR on the experimental branch.

• Tree output: Replaces flat edges/paths with nested tree (TreeNode) and ranked_leaves (RankedLeaf). Breaking API change — TraceEdge/TracePath removed, replaced by TreeNode/EdgeFromParent/RankedLeaf.
• Configurable collapse: collapse_roles (default ["OTHER"]) and collapse_min_chain_length (default 1) control which roles are collapsed. Collapsed intermediates retained in nodes dict (v1 removed them).
• Bidirectional traversal: direction="both" runs out + in BFS with shared visited set for impact analysis in one call.
• Source-relative ranking: _SOURCE_RELATIVE_PRIORITY table produces different fan-out ranking based on source node role (e.g., from SERVICE, REPOSITORY outranks CONTROLLER).
• min_result_nodes retry: When initial BFS produces fewer nodes than target, retries with doubled fan_out_cap (one retry, clamped by max_nodes_discovered).

Changed files

File	Change
mcp_trace.py	Models, BFS refactor, _build_tree, _build_ranked_leaves, bidirectional, source-relative ranking
server.py	New parameters (collapse_roles, collapse_min_chain_length, min_result_nodes, direction="both")
mcp_hints.py	_trace_structured_hints migrated from edges to tree walk
tests/test_mcp_trace.py	37 v1 tests updated + 3 removed + 22 new v2 tests = 59 total
tests/test_mcp_hints.py	3 trace hint tests updated to tree format
docs/AGENT-GUIDE.md	Trace tool reference updated
skills/explore-codebase/SKILL.md	Trace tool reference updated

Test plan

• .venv/bin/ruff check . clean
• .venv/bin/python -m pytest tests/test_mcp_trace.py -v — 54 passed, 5 skipped
• .venv/bin/python -m pytest tests/test_mcp_hints.py -v — all pass
• .venv/bin/python -m pytest tests -v — 675 passed, 13 skipped (4 pre-existing CLI path failures unrelated to this PR)

🤖 Generated with Claude Code

[HumanBean17]

Code Review: Trace Tool v2

Overall this is a solid architectural upgrade — the tree structure is cleaner than flat edges for LLM consumption, and the bidirectional mode is a useful addition. Found a couple of bugs and some cleanup items:

---

Bugs

1. id(id(...)) bug in _collapse_trivial_chains (mcp_trace.py:524)

edges_to_remove.add(id(id(out_edge)))   # ← id() of an integer, meaningless
# Also remove the original out_edge.
edges_to_remove.add(id(out_edge))       # ← this is the correct one

Line 524 calls id() on the return value of id() (an integer), producing a junk entry in the set. Harmless because line 526 correctly adds the real edge ID, but it's dead/incorrect code. Remove line 524.

2. Bidirectional advisory is dead code (mcp_trace.py:1083-1090)

if direction == "both" and pass_idx == 0:
    pass
if direction == "both" and pass_idx == 1:
    # Nodes discovered in pass 0 that would also be discovered in pass 1...
    pass

Two no-op blocks with comments about a future advisory. Either implement the advisory or remove these.

---

Code Quality

3. Triple tree walk in hints (mcp_hints.py:584-613)

The cross-service hint code walks the tree 3 times: once to find xs_nodes with empty parent_id (discarded immediately), once to build parent_map, and once more to rebuild xs_edges_final. Could be consolidated to a single pass.

4. Source-relative priority tables have identical values for SERVICE and REPOSITORY sources (both rank REPOSITORY=5, SERVICE=4, CONTROLLER=3). Intentional or should they differ?

---

Test Gap

No test verifies _build_tree handles a seed with zero edges (tree = [TreeNode(id=seed)] with no children). The empty-seed test returns early before _build_tree is called.

---

After fixing the two bugs (remove id(id(...)) line, remove dead advisory blocks), this is ready to merge.

🤖 Generated with Claude Code