Add conflict tracing and pair-local repair

DOCS.md

@@ -128,8 +128,65 @@ Use `RoutingProblem.initial_paths` to provide semantic per-net seeds. Seeds are
 | Field | Default | Description |
 | :-- | :-- | :-- |
 | `capture_expanded` | `False` | Record expanded nodes for diagnostics and visualization. |
+| `capture_conflict_trace` | `False` | Capture authoritative post-reverify conflict trace entries for debugging negotiated-congestion failures. |
+| `capture_frontier_trace` | `False` | Run an analysis-only reroute for reached-but-colliding nets and capture prune causes near their final conflict hotspots. |
 
-## 7. RouteMetrics
+## 7. Conflict Trace
+
+`RoutingRunResult.conflict_trace` is an immutable tuple of post-reverify conflict snapshots. It is empty unless `RoutingOptions.diagnostics.capture_conflict_trace=True`.
+
+Trace types:
+
+- `ConflictTraceEntry`
+  - `stage`: `"iteration"`, `"restored_best"`, or `"final"`
+  - `iteration`: Iteration index for `"iteration"` entries, otherwise `None`
+  - `completed_net_ids`: Nets with collision-free reached-target paths at that stage
+  - `conflict_edges`: Undirected dynamic-conflict net pairs seen after full reverify
+  - `nets`: Per-net trace payloads in routing-order order
+- `NetConflictTrace`
+  - `net_id`
+  - `outcome`
+  - `reached_target`
+  - `report`
+  - `conflicting_net_ids`: Dynamic conflicting nets for that stage
+  - `component_conflicts`: Dynamic component-pair overlaps for that stage
+- `ComponentConflictTrace`
+  - `other_net_id`
+  - `self_component_index`
+  - `other_component_index`
+
+The conflict trace only records dynamic net-vs-net component overlaps. Static-obstacle and self-collision details remain count-only in `RoutingReport`.
+
+Use `scripts/record_conflict_trace.py` to capture JSON and Markdown trace artifacts for the built-in trace scenarios. The default target is `example_07_large_scale_routing_no_warm_start`.
+
+## 8. Frontier Trace
+
+`RoutingRunResult.frontier_trace` is an immutable tuple of per-net post-run frontier analyses. It is empty unless `RoutingOptions.diagnostics.capture_frontier_trace=True`.
+
+Trace types:
+
+- `NetFrontierTrace`
+  - `net_id`
+  - `hotspot_bounds`: Buffered bounds around the net's final dynamic component-overlap hotspots
+  - `pruned_closed_set`
+  - `pruned_hard_collision`
+  - `pruned_self_collision`
+  - `pruned_cost`
+  - `samples`: First traced prune events near those hotspots
+- `FrontierPruneSample`
+  - `reason`: `"closed_set"`, `"hard_collision"`, `"self_collision"`, or `"cost"`
+  - `move_type`
+  - `hotspot_index`
+  - `parent_state`
+  - `end_state`
+
+The frontier trace is observational only. It reruns only the final reached-but-colliding nets in analysis mode, with scratch metrics, after the routed result is already fixed.
+
+Use `scripts/record_frontier_trace.py` to capture JSON and Markdown frontier-prune artifacts for the built-in trace scenarios. The default target is `example_07_large_scale_routing_no_warm_start`.
+
+Separately from the observational trace tooling, the router may run a bounded post-loop pair-local scratch reroute before refinement when the restored best snapshot ends with final two-net reached-target dynamic conflicts. That repair phase is part of normal routing behavior and is reported through the `pair_local_search_*` counters below.
+
+## 9. RouteMetrics
 
 `RoutingRunResult.metrics` is an immutable per-run snapshot.
 
@@ -158,6 +215,10 @@ Use `RoutingProblem.initial_paths` to provide semantic per-net seeds. Seeds are
 
 - `move_cache_abs_hits` / `move_cache_abs_misses`: Absolute move-geometry cache activity.
 - `move_cache_rel_hits` / `move_cache_rel_misses`: Relative move-geometry cache activity.
+- `guidance_match_moves`: Number of moves that matched the reroute guidance seed and received the guidance bonus.
+- `guidance_match_moves_straight`, `guidance_match_moves_bend90`, `guidance_match_moves_sbend`: Guidance-match counts split by move type.
+- `guidance_bonus_applied`: Total reroute-guidance bonus subtracted from move costs across the run.
+- `guidance_bonus_applied_straight`, `guidance_bonus_applied_bend90`, `guidance_bonus_applied_sbend`: Guidance bonus totals split by move type.
 - `static_safe_cache_hits`: Reuse count for the static-safe admission cache.
 - `hard_collision_cache_hits`: Reuse count for the hard-collision cache.
 - `congestion_cache_hits` / `congestion_cache_misses`: Per-search congestion-cache activity.
@@ -199,14 +260,21 @@ Use `RoutingProblem.initial_paths` to provide semantic per-net seeds. Seeds are
 - `verify_dynamic_candidate_nets`: Total candidate net ids returned by the dynamic net-envelope broad phase during final verification.
 - `verify_dynamic_exact_pair_checks`: Number of exact geometry-pair checks performed during dynamic-path verification.
 
-## 8. Internal Modules
+### Local Search Counters
+
+- `pair_local_search_pairs_considered`: Number of final reached-target conflict pairs considered by the bounded post-loop pair-local-search phase.
+- `pair_local_search_attempts`: Number of pair-local-search reroute attempts executed across all considered pairs.
+- `pair_local_search_accepts`: Number of pair-local-search attempts accepted into the whole routed result set.
+- `pair_local_search_nodes_expanded`: Total A* node expansions spent inside pair-local-search attempts.
+
+## 10. Internal Modules
 
 Lower-level search and collision modules are semi-private implementation details. They remain accessible through deep imports for advanced use, but they are unstable and may change without notice. The stable supported entrypoint is `route(problem, options=...)`.
 
 The current implementation structure is summarized in **[docs/architecture.md](docs/architecture.md)**. The committed example-corpus counter baseline is tracked in **[docs/performance.md](docs/performance.md)**.
-Use `scripts/diff_performance_baseline.py` to compare a fresh local run against that baseline. The counter baseline is currently observational and is not enforced as a CI gate.
+Use `scripts/diff_performance_baseline.py` to compare a fresh local run against that baseline. Use `scripts/record_conflict_trace.py` for opt-in conflict-hotspot traces and `scripts/record_frontier_trace.py` for hotspot-adjacent prune traces. The counter baseline is currently observational and is not enforced as a CI gate.
 
-## 9. Tuning Notes
+## 11. Tuning Notes
 
 ### Speed vs. optimality