propose: trace tool — multi-hop navigation shortcut (#234)

* propose: trace tool — batched multi-hop navigation shortcut

Agent drowning during multi-hop neighbors loops is reproducible and
structural. This proposal adds a server-side BFS trace tool with
role-based pruning, fan-out throttling, and trivial chain collapsing.

Refs #232

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* resolve open questions from review on trace tool proposal

- Add max_nodes_discovered budget param (default 500, clamped 100..2000)
  with BFS early-stop and advisory message
- Clarify fan_out_cap ranking: confidence primary, role as tiebreaker
- Resolve all 6 open questions with v1 decisions
- Replace "Open Questions" with "Resolved Decisions" referencing #240, #241
- Add budget_hit and budget_limit to TraceStats
- Add test_trace_budget_stops_early to test table

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* address second review: cross-service spec, collapsed markers, PR split

- Specify cross-service scaffolding edge rules: which internal edges
  the engine follows, that they appear in output, and hop numbering
- Add collapsed/collapsed_intermediates fields to TraceEdge for
  per-edge discoverability of collapsed chains
- Document max_nodes_discovered as compute guardrail (pre-pruning)
  with explicit intent statement
- Add known v1 trade-off note for static fan_out_cap role tiebreaker
- Document ids single-string normalization
- Split PR-TRACE-1 into 1a (core BFS) and 1b (pruning + cross-service)
- Add resolved decisions 7-10 from second review

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* add agent tool selection heuristics, experimental branch targeting

- Add "Agent tool selection: trace vs neighbors" section with:
  - Decision table mapping question intents to trace/neighbors
  - Reasoning preamble update for the trace Q-class
  - Hint system updates: fan-out, loop escalation, drill-down,
    budget hit, cross-service boundary hints
  - Skill decision tree rows for trace use cases
- Mark proposal as experimental, target branch is `experimental`
  not `master`
- Add "Experimental validation" section with quantitative criteria
  (multi-hop accuracy, tool call reduction, no regression, latency)
  and qualitative criteria (agent tool selection, pruning quality)
- Add graduation process and rollback plan
- Update Appendix A to acknowledge the v2 decision was correct
  and trace is an experiment to validate the hypothesis

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* redesign cross-service: boundary-stop instead of seamless traversal

Cross-service traversal now stops at service boundaries instead of
automatically following into downstream services. Rationale:
- Prevents context explosion (multi-service results defeat pruning)
- Preserves agent autonomy (agent decides whether to continue)
- Avoids hop budget waste on scaffolding edges

Changes:
- BFS records cross-service edges with cross_service_boundary=True
  and stops (does not add downstream Route to frontier)
- Downstream Route node included in nodes dict for agent visibility
- Scaffolding edges (DECLARES_CLIENT/PRODUCER) followed only to
  reach cross-service edge, not into downstream service
- Removed: scaffolding edge hop-counting caveats, mid-traversal
  advisories, EXPOSES-following into downstream handler
- Added: cross_service_boundary field on TraceEdge
- Added: "Why not seamless traversal" section explaining rationale
- Updated: algorithm pseudocode, tests, hints, decision tree,
  Appendix B comparison table
- New test: test_trace_cross_service_boundary_stops

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* add parent_edge_id to TraceEdge for lightweight tree reconstruction

Reviewed concern that flat edge list doesn't express hierarchy.
Added parent_edge_id (nullable) to TraceEdge instead of full tree field.
Seed edges have parent_edge_id: null; child edges reference the edge
that reached their from_id. Enables O(1) tree reconstruction without
duplicating node payloads. Full tree field deferred to v2 (#240).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* address review: batched queries, filter ordering, test gaps

Address 9 review points from PR #234 comment:

Must-address:
- Batched Cypher queries: single query per hop, not per frontier node
- Post-collapse parent_edge_id recomputation after trivial chain merging
- Path enumeration capped at 10x max_paths to prevent exponential blowup
- NodeFilter (hard gate) vs prune_roles (soft gate) ordering clarified

Worth addressing:
- OVERRIDES traversal test added (interface resolution)
- Scaffolding edges exempt from fan_out_cap
- Test coverage gaps: multi-seed, string normalization, collapse disabled,
  depth/budget clamping, filter vs prune_roles interaction, parent_edge_id
- Removed redundant leaf_role from TracePath (available via leaf.role)
- Branch topology for PR-TRACE sequencing specified

Minor:
- "imports but does not modify" clarified for mcp_v2.py
- ids: str | list[str] divergence from neighbors documented

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: HumanBean17