feat(tools): 添加增量 trace 结构回归门禁

[Qiyuanqiii]

背景与定位

Related to #5

Issue #5 的现有实现主要集中在全量扫描、数据清理、修复产物和人工复核流程。当前 v0.1.4 数据仍包含 383 个需要处理或复核的结构 finding，直接将全量 finding 数量设为 CI 条件，会让后续所有数据 PR 持续失败。

本 PR 不再增加另一套全量清理器，而是提供一个独立的增量回归门禁：比较 baseline 与 candidate，只阻止本次修改新引入的 trace 结构问题。

增量判定语义

• baseline 已有 finding 作为 legacy debt 保留，不阻断。
• candidate 新增 finding 时返回退出码 1。
• candidate 解决历史 finding 时记录为 resolved，不阻断。
• 输入或行号无法安全解析时返回退出码 2。
• 新增 entry 中存在的结构问题同样会被识别为回归。
• 工具只检测和报告，不修改或重排 entries.jsonl。

检测范围

• trace 内 {file, line, code} 完全相同的重复节点。
• 与 entry_point 同文件且完全位于入口之前的节点。
• 与 critical_operation 同文件且完全位于关键操作之后的节点。
• 支持整数及 "start-end" 区间行号。
• 跨文件节点不参与行号比较。
• 与边界相交的区间不会被当作明确越界。

稳定指纹

finding 指纹由 entry_id、类型、file、line、code 和出现序号组成，不包含 trace 数组索引与 desc。

因此以下修改不会制造假回归：

• 只修改节点说明文本。
• 在问题集合不变时移动数组索引。
• 调整其他无关 entry。

同一节点新增第三次或第四次重复仍会被分别检测。

交付内容

• scripts/check_trace_regressions.py：增量比较器及 JSON/Markdown 报告生成。
• scripts/README_trace_regression_gate.md：CI 用法、退出码、策略和限制。
• tests/test_trace_regression_gate.py：11 项边界及 CLI 回归测试。

真实数据结果

项目	Baseline	Candidate
Entries	408	408
Trace nodes	2,073	2,073
Structural findings	383	383
New findings	-	0
Resolved findings	-	0
Unchanged legacy findings	-	383

门禁结果：PASS

383 个历史 finding 的组成与 Issue #5 全量检测口径一致：

• Duplicate：7
• Before entry：139
• After critical：237

验证命令

python -m unittest discover -s tests -v
python scripts/check_trace_regressions.py \
  --base-ref origin/main \
  --candidate data/entries.jsonl
python -m compileall -q scripts tests
git diff --check origin/main...HEAD

验证结果：

• unittest：Ran 11 tests，OK。
• 全量数据：408 entries、2,073 trace nodes。
• 增量结果：new=0、resolved=0、unchanged=383。
• 编译及 git diff --check：通过。

验证截图

本 PR 不关闭 Issue #5，也不替代现有历史清理和人工复核方案；它提供的是可立即用于后续数据变更的增量质量门禁。