autoresearch-finalize

完成 Autoresearch

将杂乱的 autoresearch 分支整理为干净、相互独立的分支——每个逻辑变更对应一个分支，且每个分支都从合并基点开始。

步骤 1 — 分析并提出分组方案

1. 读取 .auto/log.jsonl（旧版：autoresearch.jsonl）。仅筛选保留的实验。
2. 阅读 .auto/prompt.md（旧版：autoresearch.md），了解背景。
3. 将所有短提交哈希扩展为完整哈希：git rev-parse <short_hash>
4. 获取合并基点：git merge-base HEAD main
5. 对每个保留的提交获取 diff 统计（第一个使用 $BASE..<commit>，后续使用 <prev_kept>..<commit>）。
6. 将保留的提交分组为逻辑变更集：
   • 保持应用顺序。 第 N 组必须排在第 N+1 组之前。
   • 任何两个分组都不得修改同一个文件。 每个分支都会独立应用到合并基点；文件重叠会导致冲突。如果两个分组修改了同一个文件，就将它们合并为一个分组。
   • 注意跨文件依赖。 每个分支都是独立的，因此如果组 1 在 api.js 中新增 API，而组 2 在 parser.js 中调用该 API，那么组 2 的分支单独使用时将无法运行。提出分组方案时，请标明依赖关系：“组 2 依赖组 1 — 请一起审查。”如果依赖关系紧密，就合并这两个分组。
   • 让每个分组保持小而聚焦。 每个分组只包含一个想法、一个主题。
   • 不要硬编码分组数量。 可以是 2 个，也可以是 15 个。

向用户展示拟议的分组方案：

Proposed branches (each from merge-base, independent):

1. **Switch test runner to forks pool** (commits abc1234, def5678)
   Files: vitest.config.ts, package.json
   Metric: 42.3s → 38.1s (-9.9%)

2. **Tune worker count and timeouts** (commits ghi9012, jkl3456)
   Files: test/setup.ts
   Metric: 38.1s → 31.7s (-16.8%)

继续前等待用户批准。

步骤 2 — 编写 groups.json 并运行

编写 groups.json：

{
  "base": "<full merge-base hash>",
  "trunk": "main",
  "final_tree": "<full hash of current HEAD>",
  "goal": "short-slug",
  "groups": [
    {
      "title": "Switch to forks pool",
      "body": "Why + what changed.\n\nExperiments: #3, #5\nMetric: total_time 42.3s → 38.1s (-9.9%)",
      "last_commit": "<full hash of last kept commit in this group>",
      "slug": "forks-pool"
    }
  ]
}

关键规则：

• last_commit 必须是完整哈希。 使用 git rev-parse 扩展 jsonl 中的短哈希。
• 任何两个分组都不得包含同一个文件。 脚本会验证这一点，违反时将失败。

然后运行：

bash <SKILL_DIR>/finalize.sh /tmp/groups.json

该脚本会从合并基点为每个分组创建一个分支，验证这些分支的并集与原始分支一致，并打印摘要，其中包含所有分支、清理命令，以及 .auto/ideas.md 中的想法（旧版：autoresearch.ideas.md）。

创建失败时：回滚（删除分支、恢复原始分支、弹出 stash）。 验证失败时：以非零状态退出，但保留分支供检查。

步骤 3 — 报告

脚本运行完毕后，向用户报告：

• 创建的分支及每个分支包含的内容
• 整体指标提升情况（基准值 → 最佳值）
• 显示脚本摘要输出中的清理命令

边缘情况

• 只有 1 个保留的实验：创建一个分支即可——不要强行拆分。
• 不同分组之间存在文件重叠：脚本会失败并报错指出文件名。合并存在重叠的分组后重试。
• 分支上存在非实验提交：跳过这些提交——仅处理 jsonl 中保留的实验。