tools: add trace structure cleanup

[ruirui6946]

Summary

• add a standard-library Python utility that detects exact trace duplicates, same-file boundary anomalies, and cross-file comparisons
• provide conservative report mode and deterministic fix mode, with verify=1 entries protected by default
• include the generated fixed JSONL, detailed CSV log, machine-readable report, usage documentation, and regression tests

Root cause and strategy

VulnGym trace annotations had no automated structural validation. Exact duplicate steps and same-file nodes outside the entry/critical boundaries could therefore remain in the dataset, while naïve line sorting could corrupt valid cross-file call chains.

The new utility never reorders trace nodes. It compares inclusive integer/range spans only against same-file boundaries, automatically removes only wholly out-of-bound nodes allowed by the selected policy, and retains overlapping ranges, description conflicts, boundary inversions, and verified-entry findings for manual review. Default report mode keeps the JSONL byte-identical.

Full dataset result

• scanned 408 entries and 2,073 trace nodes
• detected 7 exact duplicate candidates, 62 entry-boundary findings, and 186 critical-boundary findings
• recorded 1,658 skipped cross-file boundary comparisons without changing their order
• removed 4 clearly out-of-bound nodes from entry-00103, entry-00185, entry-00320, and entry-00511
• retained ambiguous or verified findings with explicit manual_review actions

Validation

• python -m unittest discover -s tests -v — 20 tests passed
• verified entry/report join invariants and all entry-level SCHEMA.md constraints
• reproduced the JSONL, CSV, and report byte-for-byte on Ubuntu 24.04 with Python 3.12.3
• git diff --cached --check

Closes #5