feat: add conservative trace structure cleanup

[Sam-Hui-dot]

Summary

This PR adds a conservative, reproducible workflow for detecting and reviewing structural anomalies in VulnGym trace annotations.

It covers:

• exact duplicate trace nodes identified by {file, line, code};
• same-file nodes before entry_point;
• same-file nodes after critical_operation;
• integer and range-based line numbers;
• cross-file trace preservation without line-based reordering;
• schema validation and deterministic report generation;
• explicit manual-review handling for semantically ambiguous findings.

Dataset audit

The complete data/entries.jsonl dataset was scanned:

• 408 entries;
• 2,073 trace nodes;
• 7 exact duplicate candidates;
• 139 before-entry findings;
• 237 after-critical findings;
• 1,658 cross-file comparisons skipped without reordering;
• 379 verified findings protected;
• 4 entries requiring manual review.

All 7 duplicate candidates are in verified entries and/or contain conflicting descriptions, so they are preserved rather than merged automatically.

Conservative fix decision

The default fix run applies zero changes to the canonical dataset.

The four unverified order findings are recorded in reports/trace_needs_human.csv because source declaration order does not necessarily represent runtime execution order:

• entry-00103
• entry-00185
• entry-00320
• entry-00511

Deleting these nodes solely from source-line comparisons could remove valid control-flow or call-chain evidence.

The implementation still supports deterministic deletion of clearly safe findings through the explicit structural policy. Synthetic regression tests cover this behavior.

Deliverables

• scripts/trace_cleanup.py

  • standard-library implementation;
  • check and fix modes;
  • conservative and structural order policies;
  • integer/range line parsing;
  • duplicate and schema validation;
  • optional upstream source verification.

• tests/test_trace_cleanup.py

  • 25 regression tests covering duplicate handling, conflicting descriptions, verified-entry protection, order policies, cross-file behavior, overlapping ranges, idempotence, schema compatibility, and generated artifacts.

• data/entries.trace_fixed.jsonl

  • 408-row fixed artifact;
  • byte-identical to the canonical input under the conservative policy.

• reports/trace_findings.csv

  • complete finding-level audit log.

• reports/trace_fix_diff.csv

  • automatic modification log; currently contains only the header because no real-world finding was proven safe to delete.

• reports/trace_needs_human.csv

  • four semantically ambiguous entries requiring manual review.

• reports/trace_structure_report.json

• reports/trace_structure_report.md

  • machine-readable and reviewer-friendly aggregate reports.

• reports/trace_cleanup_acceptance_matrix.md

  • maps the Issue 【2026犀牛鸟】清理 VulnGym 调用链顺序异常和重复节点 #5 acceptance criteria to the implementation and validation evidence.

• scripts/README_trace_cleanup.md

  • usage, policy, limitations, and review guidance.

Validation

The following checks passed:

• 25/25 unit tests;
• complete dataset scan;
• schema and report-mapping validation;
• integer and range line validation;
• cross-file ordering protection;
• fix-mode idempotence;
• byte-level output stability;
• LF and trailing-whitespace validation;
• upstream source verification for 12 occurrences across 8 source files;
• no generated Python cache files.

Closes #5