verify-llm-artifacts

验证 LLM 工件审查结果

对 .beagle/llm-artifacts-review.json 进行第二轮验证。检测阶段优先保证召回率；本阶段优先保证精确率，避免 Agent 删除或“清理”仍有必要的代码。

何时运行

• 在 review-llm-artifacts 技能之后运行（尤其是完整项目扫描之后）。
• 在 fix-llm-artifacts 技能之前运行，尤其是审查结果包含删除项、死代码或高风险时。
• 以往运行中标记了不应删除的工件时运行。

输入

• 必需： 已完成审查的 .beagle/llm-artifacts-review.json。
• 可选： $ARGUMENTS — --priority-only（先验证 dead_code 和任何 fix_action 为 delete 的条目，再验证其他条目）、--id N（单个审查结果 ID）。

如果审查文件缺失，则退出并显示：Run the review-llm-artifacts skill first.

前置技能

1. 加载 review-verification-protocol 技能 — 通用的反误报规范，包括反臆造门槛（在做出任何判定前，先从刚读取的源文件中复述工件）。第 1 步中的加载 + 回显门槛，是本技能对该规则的具体落实。
2. 加载 llm-artifacts-detection 技能 — 判断哪些情况属于实际问题的类别标准。

说明

硬性门槛

在声称验证完成之前，必须满足以下客观条件：

1. 输入解析： 第 1 步中的 JSON 加载命令以状态码 0 退出（无回溯信息）。通过： 磁盘上的 .beagle/llm-artifacts-review.json 是有效 JSON。
2. 先回显，再判定： 第 1 步已打印完整的审查结果表（findings[] 中每条记录占一行，包含 id、file、line、category、description），且数据来自本轮解析的 JSON。通过： 输出中包含该表，且行数等于 len(findings) — 在此之前尚未开始做出任何判定。
3. ID 锁定： 第 1 步已记录 findings[] 中确切的 ID 集合，并明确列出。每个 results 条目均与一个已锁定的 ID 一一对应 — 既不增加，也不遗漏。通过： 已打印锁定的 ID 列表；如果任何时候出现一个找不到匹配锁定 ID 的疑似审查结果，则停止（参见第 1 步的 ID 锁定）。
4. 先取证，再判定： 对每条进行判定的审查结果，均已根据其 category 应用 references/verification-checklist.md（或记录类别为何不适用），并在 checks_performed 中记录匹配的字符串。通过： 每个 status 至少有一项由检查清单支持的检查，或在 notes 中有明确的不适用说明。
5. 输出契约： 写入 .beagle/llm-artifacts-verification.json 后，第 4 步中的验证命令以状态码 0 退出；summary 中各状态的计数与 results 中相应状态的条目数一致；results 的 ID 集合与门槛 3 中锁定的 ID 集合完全一致。通过： JSON 符合架构要求，且 results IDs == 锁定的 IDs == 源 findings[] IDs。

1. 加载、回显并锁定 ID

这是一个两部分的关卡。解析不等于加载——json.load 成功退出（状态码为 0），只能证明文件格式正确，并不能证明你已将其中的发现加载到上下文中。进行任何判定之前，必须先回显实际内容。

1a. 解析并回显发现表。

打印从已解析的 findings[] 数组中读取的每条发现——不能凭记忆、分支名称或周边文件：

python3 - <<'PY'
import json
r = json.load(open('.beagle/llm-artifacts-review.json'))
f = r['findings']
print(f"git_head={r.get('git_head')} scope={r.get('scope')} count={len(f)}")
print("| id | file | line | category | description |")
print("|----|------|------|----------|-------------|")
for x in f:
    desc = (x.get('description') or '').replace('|', '\\|')[:80]
    print(f"| {x['id']} | {x.get('file')} | {x.get('line')} | {x.get('category')} | {desc} |")
print("ids=" + ",".join(str(x['id']) for x in f))
PY

**通过条件：**命令以 0 退出，且输出中显示该表（每条发现占一行）。

**发现的唯一来源是已解析的 findings[] 数组。**不要根据分支名称、工作目录或周边文件推断发现。如果你对发现的印象与回显的表格不一致，以表格为准——丢弃原有印象，仅根据上方的行进行判定。

1b. 锁定 ID（任何判定前的硬性关卡）。

准确记录上方 ids= 行中的 ID 集合，并立即写出，例如 Locked ids: {1, 2, 3, 4, 5, 6, 7}。这就是锁定的 ID 集合。第 4 步中写出的每条结果都必须与该集合一一对应：不能添加或遗漏任何 ID。第 4 步的输出 ID 检查必须引用此锁定集合，而不能重新推导集合。

如果在验证过程中，你发现自己正要判定一个 ID 不在锁定集合中的发现，或正要为锁定行中未出现的文件写出结果，请停止。这是 Agent 错误（你是在依据记忆或上下文进行推理，而不是依据报告）。通过上方的回显命令重新读取 findings[]，然后重新开始判定。不要将此类发现记为 false_positive（参见第 3 步“状态规范”）。

记录报告中的 git_head 和 scope（它们已由 1a 打印）。如果工作树不再匹配（可选的严格模式：与 git rev-parse HEAD 比较），请警告行号可能已变动。

2. 排列发现

默认顺序：

1. category == "dead_code"、fix_action == "delete" 或 risk == "High"
2. 其余发现按 (risk descending, id ascending) 排序

使用 --priority-only 时，在处理完 dead_code 类别和所有 fix_action: delete 后停止（仍须为已处理的发现写出完整输出）。

3. 验证每项发现

对于每项发现，请遵循 references/verification-checklist.md。每个类别的第一项检查都是存在性前置条件：运行任何符号／用法检查之前，先确认所引用的 file 在 source_git_head 中存在。

每项发现的最低证据要求：

• 先确认存在：确认 file 在 source_git_head 中存在（使用 git cat-file -e <head>:<file> 或 test -f）。所引用的文件不存在，并非常规情况——这要么是已删除文件的发现（请注明），要么说明你查看的不是实际报告。若出现大量文件缺失结果，请停止并重新读取 findings[]（步骤 1a）。不得默默忽略缺失文件。
• 阅读所引用位置的文件，并查看足够的上下文以作出判断（父级符号、导入项）。
• 对于未使用／死代码的主张：请在仓库中搜索（符号、导出项、字符串钩子），除非问题纯属风格问题且无需删除。

通过：checks_performed 只列出你实际运行的检查（例如 file_exists、read_symbol、ripgrep_symbol）；notes 引用决定性观察结果。

分配一个状态：

status	含义
confirmed_issue	报告中的发现有效；采取相应操作是合适的。
false_positive	报告中的发现无效（事实错误，或“修复”会造成危害）；不要自动修复。
inconclusive	需要人工或产品上下文判断；在 fix-llm-artifacts 中按风险项处理。

状态纪律（硬性规则）：false_positive 表示*“报告中的发现无效。”* 绝不表示*“报告中没有此发现。”* 如果遇到一项看似存在、却无法与锁定 id 集合中的条目（步骤 1b）匹配的发现，这是Agent 错误，而非误报——请停止，使用步骤 1a 的回显命令重新读取 findings[]，然后重新开始判定。禁止为锁定集合之外的 id 写入 false_positive（或任何其他状态）。

4. 编写输出

如有需要，创建 .beagle。写入 .beagle/llm-artifacts-verification.json：

{
  "version": "1.0.0",
  "created_at": "2026-04-19T12:00:00Z",
  "source_report": ".beagle/llm-artifacts-review.json",
  "source_git_head": "<from review>",
  "review_scope": "all|changed",
  "results": [
    {
      "id": 1,
      "status": "confirmed_issue|false_positive|inconclusive",
      "confidence": "high|medium|low",
      "checks_performed": ["file_exists", "read_symbol", "ripgrep_symbol", "export_trace"],
      "notes": "1-3 sentences of evidence"
    }
  ],
  "summary": {
    "confirmed_issue": 0,
    "false_positive": 0,
    "inconclusive": 0
  }
}

验证写入的文件：

python3 -c "import json; json.load(open('.beagle/llm-artifacts-verification.json'))"

通过：命令退出码为 0；重新打开文件并确认 (a) summary 与 results 一致（统计每种 status 的数量），且 (b) results 中的 id 集合与步骤 1b 中的锁定 id 集合完全一致——不得新增或遗漏任何 id。如果 id 集合不一致，则验证失败：不要交付；请重新读取 findings[]（步骤 1a）并进行核对。

5. 向用户总结

打印一张简短的 Markdown 表格：id、category、原始单行描述、判定、confidence。

最后列出：

• 已确认、误报和无法确定的数量。
• 建议：仅对已确认的问题运行 fix-llm-artifacts（存在验证文件时请参阅该技能）。

规则

• 不要臆造新问题；只判定现有的 findings[] 条目。
• 如果删除可能影响动态用法或跨仓库用法，优先选择 inconclusive 而非 confirmed_issue。
• 按照源报告准确保留 id 值。

集成

• **fix-llm-artifacts：**此文件存在时，请用它跳过 false_positive id，并将 inconclusive 视为风险修复。
• fix_action 的保留：fix_action 字段（refactor／delete／simplify／extract）由 review-llm-artifacts 输出，并由 fix-llm-artifacts 用作风险门槛；验证时应原样传递，不得重新验证。