add trace tool v2 implementation plan (TRACE-V2)

[HumanBean17]

Summary

• Adds plans/active/PLAN-TRACE-TOOL-V2.md implementing propose/active/TRACE-TOOL-V2-PROPOSE.md as a single PR.
• Four enhancements: tree output format (replaces flat edges/paths), configurable collapse_trivial heuristic (collapse_roles, collapse_min_chain_length), source-relative fan-out ranking, bidirectional traversal (direction="both"), and min_result_nodes post-pruning retry.
• 37 updated v1 tests + 22 new tests (59 total). Breaking API change on TraceOutput.

Scope

File	Change
plans/active/PLAN-TRACE-TOOL-V2.md	New plan file (this PR)

Out of scope (do NOT touch)

• mcp_trace.py, server.py, mcp_hints.py — implementation in a separate PR after plan approval.
• docs/AGENT-GUIDE.md, skills/explore-codebase/SKILL.md — updated during implementation.
• Graph schema, ontology, indexer, CLI.

🤖 Generated with Claude Code

[HumanBean17]

Plan Review — TRACE-TOOL-V2

Plan is well-structured, honest about risks, and closely aligned with the proposal. A few items to address before implementation begins:

Must-fix

1. Test count inconsistency in PR breakdown table

The breakdown table says all 40 v1 tests updated + 21 new tests but the detailed test section lists 37 updated + 3 removed/replaced + 22 new = 59 total. The PR description header and Definition of Done both say "37 + 22 = 59". The breakdown table should match: "37 v1 tests updated + 3 removed + 22 new (59 total)".

2. __all__ export update not mentioned

mcp_trace.py currently exports TraceEdge, TracePath via __all__. The plan removes those and adds TreeNode, EdgeFromParent, RankedLeaf but never mentions updating __all__. Add a bullet to step 1 to cover this — any consumer doing from mcp_trace import * will break silently otherwise.

3. _build_tree helper needs more detail

This is the most correctness-critical piece of the entire plan, but the description is a one-liner: "Tree nesting matches BFS parent-child structure." It must handle multi-seed roots, collapsed intermediate reparenting, cross-service boundary metadata, and the flat→nested conversion itself. Consider adding pseudocode or a more detailed contract so the implementation step is unambiguous.

Should-address

4. Bidirectional shared visited set — consider an advisory

The shared visited set is a reasonable optimization, but when it suppresses nodes in the second direction, agents have no signal that completeness was traded for efficiency. Consider emitting an advisory like "N nodes were explored in the first direction and not re-visited in the second" when direction="both" and the shared set actually suppresses exploration.

5. collapse_trivial=False vs collapse_roles interaction

The plan adds collapse_roles but doesn't specify what happens when collapse_trivial=False while collapse_roles is set. The proposal says collapse_trivial is the "master toggle" — worth stating explicitly in the plan too.

Minor

• The "Independent of" column in the PR breakdown table is vestigial (single-PR plan with no sub-PRs). Could remove for clarity.

Overall: solid plan. Happy to approve once the three must-fix items are addressed.