Add iteration trace diagnostics for seed43

DOCS.md

@@ -130,6 +130,7 @@ Use `RoutingProblem.initial_paths` to provide semantic per-net seeds. Seeds are
 | `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. |
+| `capture_iteration_trace` | `False` | Capture per-iteration and per-net route-attempt attribution for negotiated-congestion diagnosis. |
 
 ## 7. Conflict Trace
 
@@ -186,7 +187,37 @@ Use `scripts/record_frontier_trace.py` to capture JSON and Markdown frontier-pru
 
 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
+## 9. Iteration Trace
+
+`RoutingRunResult.iteration_trace` is an immutable tuple of negotiated-congestion iteration summaries. It is empty unless `RoutingOptions.diagnostics.capture_iteration_trace=True`.
+
+Trace types:
+
+- `IterationTraceEntry`
+  - `iteration`
+  - `congestion_penalty`: Penalty in effect for that iteration
+  - `routed_net_ids`: Nets rerouted during that iteration, in routing order
+  - `completed_nets`
+  - `conflict_edges`
+  - `total_dynamic_collisions`
+  - `nodes_expanded`
+  - `congestion_check_calls`
+  - `congestion_candidate_ids`
+  - `congestion_exact_pair_checks`
+  - `net_attempts`: Per-net attribution for that iteration
+- `IterationNetAttemptTrace`
+  - `net_id`
+  - `reached_target`
+  - `nodes_expanded`
+  - `congestion_check_calls`
+  - `pruned_closed_set`
+  - `pruned_cost`
+  - `pruned_hard_collision`
+  - `guidance_seed_present`
+
+Use `scripts/record_iteration_trace.py` to capture JSON and Markdown iteration-attribution artifacts. Its default comparison target is the solved seed-42 no-warm canary versus the pathological seed-43 no-warm canary.
+
+## 10. RouteMetrics
 
 `RoutingRunResult.metrics` is an immutable per-run snapshot.
 
@@ -272,7 +303,7 @@ Separately from the observational trace tooling, the router may run a bounded po
 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. Use `scripts/record_conflict_trace.py` for opt-in conflict-hotspot traces, `scripts/record_frontier_trace.py` for hotspot-adjacent prune traces, and `scripts/characterize_pair_local_search.py` to sweep example_07-style no-warm runs for pair-local repair behavior. 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, `scripts/record_frontier_trace.py` for hotspot-adjacent prune traces, `scripts/record_iteration_trace.py` for per-iteration negotiated-congestion attribution, and `scripts/characterize_pair_local_search.py` to sweep example_07-style no-warm runs for pair-local repair behavior. The counter baseline is currently observational and is not enforced as a CI gate.
 
 ## 11. Tuning Notes