add trace tool v2 proposal (#240)

[HumanBean17]

What

Added proposal file propose/active/TRACE-TOOL-V2-PROPOSE.md for trace tool v2 enhancements tracked in #240.

Why now

The trace tool v1 shipped on experimental (PR-TRACE-1a through PR-TRACE-4). Four concrete shortcomings emerged during review and production use that justify a v2 proposal.

Highlights

• Tree output replaces flat edges + paths with nested TreeNode structure. Breaking API change.
• Configurable collapse heuristic (collapse_roles, collapse_min_chain_length) for SERVICE delegate patterns.
• Source-relative fan-out ranking with min_result_nodes post-pruning floor.
• Bidirectional traversal (direction="both") in a single call.
• Cross-service seamless traversal (Document Kuzu MAP-as-STRING pattern in plan + prompts #6 from trace tool: v2 enhancements — bidirectional traversal, richer heuristics, configurable ranking #240) already shipped in add cross_service flag to trace tool #256.
• Single PR, no re-index, no ontology bump.

Tests

Docs-only; baseline unchanged.

Out of scope

• Configurable rank_by path ranking (deferred)
• Adaptive escalation / neighbors loop detection (requires session state)
• Per-codebase YAML tuning
• CLI integration (trace tool: CLI integration and legacy method deprecation #241)

[HumanBean17]

Review: Trace Tool V2 Proposal

Well-structured proposal — concrete problem statements, exceptional test plan (40 existing + 22 new tests mapped), and good resolved-decisions section. A few items to address before this lands:

Issues

1. Duplicate section numbering — "What this proposal changes" has two items numbered 4 (breaking API change, no graph schema changes). Renumber to 4–7.

2. confidence dropped from edge metadata — v1 TraceEdge included confidence. The new EdgeFromParent type has no confidence field. Is this intentional? If confidence is no longer surfaced per-edge, the proposal should say why. If it's an oversight, add confidence: float | None to EdgeFromParent.

3. Bidirectional merge — "other direction records the edge" is ambiguous — The merge semantics say "the other direction records the edge but does not duplicate the node." Does the non-first direction (a) show a TreeNode with edge_from_parent but no children, (b) drop the edge entirely, or (c) add an advisory? Option (a) seems most useful for agents. A one-liner clarification would help the implementer.

4. cross_service + direction="both" interaction — Not specified whether boundary stopping applies symmetrically in both directions during bidirectional traversal. Worth a brief note.

5. min_result_nodes retry has no upper bound — Doubling fan_out_cap is fine for small caps, but if already at 50 the retry goes to 100. Consider noting that existing BFS budget clamping still caps the retry.

Minor

• _SOURCE_RELATIVE_PRIORITY: the REPOSITORY row is missing a CONTROLLER entry (should be priority 1 for completeness, matching other rows).
• Line refs in mcp_hints.py (526, 557, 571) will likely drift — consider referencing by function name instead.
• Post-merge follow-ups mention docs/AGENT-GUIDE.md — confirm skills/explore-codebase/SKILL.md also gets the parallel update.

Overall: solid proposal, the issues above are clarifications not design problems. 👍