plan: trace tool — multi-PR implementation plan and agent prompts

[HumanBean17]

Summary

• Adds plans/active/PLAN-TRACE-TOOL.md — execution-ready implementation plan for the trace MCP tool (5 PRs, 34 named tests, dependency graph, cross-PR risks).
• Adds plans/active/AGENT-PROMPTS-TRACE-TOOL.md — per-PR agent handoff prompts with scope contracts, iteration loop test subsets, sentinel checks, and manual evidence commands.

Implements propose/active/TRACE-TOOL-PROPOSE.md planning phase. This is plan-only — no code changes.

PR breakdown

PR	Scope	Tests
PR-TRACE-1a	Core BFS engine (mcp_trace.py)	23
PR-TRACE-1b	Pruning, collapsing, cross-service	11
PR-TRACE-2	MCP registration (server.py)	2
PR-TRACE-3	Hints + skill decision tree	5
PR-TRACE-4	Documentation sweep	docs-only

Landing order: 1a → 1b → 2 / 3 (parallel) → 4

Validation

.venv/bin/ruff check .
.venv/bin/python -m pytest tests -v

🤖 Generated with Claude Code

[HumanBean17]

Plan review

Thorough plan, well-aligned with the propose. The PR decomposition is sound — the 1a/1b split is a genuine review-surface separation, and the parallel 2/3 after 1b is correct. Agent prompts are production-quality. A few issues before implementation starts:

1. Duplicate test name: test_trace_filter_vs_prune_roles (medium)

Same name in both 1a (#17) and 1b (#11). When 1b merges, it overwrites the 1a version — so the unique test count is 33, not 34. Either rename the 1a stub (e.g. test_trace_prune_roles_param_accepted_noop) or note the replacement explicitly and fix the count.

2. "Independent of" column header is inverted (low)

The values in the PR breakdown table represent dependencies, not independencies. Rename to "Depends on" or "Blocked by".

3. Import contract diverges from propose (low)

Propose says trace imports Edge from mcp_v2.py; plan drops it in favor of _node_ref_from_row and _node_kind_from_id. Likely intentional (trace defines its own TraceEdge) but not called out. Add a note in "Resolved design decisions."

4. Hint template count in PR-TRACE-3 plan section (low)

File-by-file says "five new hint templates" but implementation is 4 server-side (the 5th is client-side only). Agent prompt correctly says "Four." Align the plan text.

5–6. Trivial

• ruff check on SKILL.md in PR-TRACE-3 prompt (harmless, drop it)
• PR-TRACE-3 prompt doesn't clarify which hint tests go in test_mcp_hints.py vs test_mcp_trace.py

Issue #1 should be fixed before PR-TRACE-1a starts. The rest are cleanup.