lazygophers/trellisx-cleanup

trellisx-cleanup — 批量收尾全部已完成 task

trellis 逐个 task.py finish/archive 收尾单任务; 多个 task 完成后堆积 (残留已合并 worktree、看板已完成行膨胀、未归档 completed 任务) 时缺批量收口。本 skill 一次清理三类残留, 复用 trellisx-finish.py (单任务全链) + trellisx-taskmd.py (看板) + worktree 安全销毁判据, 不重写 git 逻辑。

做三件事 (用户三需求)

| # | 需求 | 实现 | | --- | --- | --- | | ① | 清理所有已完成的 worktree | 已合并+干净的 worktree 销毁 (沿用 trellisx-worktree.py archive 安全判据: merge-base --is-ancestor); 脏/未合并自动保留, 禁丢提交 | | ② | 归档所有已完成的任务 | 逐个 trellisx-finish.py --task <tid> (commit→merge --no-ff→archive→销 worktree, 逐个提交, 幂等可重入) | | ③ | 清理已完成任务的 task.md | trellisx-taskmd.py cleanup --days N 删看板"已完成"行 (默认 --days 0 全删) |

完成判定 = completed ∪ merged (并集)

• completed: .trellis/tasks/<tid>/task.json 的 status == "completed" 且未归档。
• merged: worktree 干净 且 分支已 merge 回主分支 (即使 task.json 未置 completed 的孤儿 worktree 也清)。
• 当前 active task 永不纳入 (task.py current 命中的 tid 排除, 防销正在用的)。

强制三段护栏 (破坏性操作, 不可跳)

销毁 worktree + 归档任务 + 删看板行 = 破坏性。必须走: dry-run 报告 → AskUserQuestion 确认 → --apply 执行。禁跳过确认直接 --apply, 禁用"建议清理"软措辞替代确认工具。

1. dry-run (默认, 只读): 不带 --apply 跑, 打印将归档的 task、将销的 worktree、将保留的 worktree (脏/未合并)、将删的看板行阈值。不改任何状态。

   python3 .trellis/scripts/trellisx-cleanup.py
   

2. 确认: 把 dry-run 清单经 AskUserQuestion 工具呈给用户 (列出 tid + worktree 路径), 用户批准才进第 3 步。
3. 执行: 用户确认后跑 --apply。

   python3 .trellis/scripts/trellisx-cleanup.py --apply [--days 0] [--message "<提交消息>"]
   

执行后 AI 必做 (脚本做不到)

• 核对失败项: 某 task 收尾非 0 退出 (多为合并冲突) → 脚本报告并继续其余、最终非 0 退出。AI MUST 检失败清单, 逐个转手动解冲突后重跑, 禁当成功。
• 保留项跟进: 脏/未合并 worktree 被保留 → 提示用户先提交/合并再重跑清理。

边界

• 只做 git (worktree/分支/merge/archive) + 看板 (task.md) 的确定性操作; 不改源码、不碰 task.json 真值 (经 task.py archive 间接归档)。
• 只处理已完成 (completed ∪ merged); 禁碰 in_progress / 悬挂后台 Task —— 那些仍在执行, 归 trellisx-flow 收尾 (AI 层 TaskList → TaskStop), 不属本批量清理层。
• worktree 销毁完全沿用 trellisx-worktree.py 既有安全判据, 不新增强删路径 —— 脏树或分支未合并一律保留。
• 脚本缺失 (项目未跑 apply) → 提示先 /trellisx-apply 复制脚本到 .trellis/scripts/。
• 与 trellisx-workspace 关系: workspace 维护单个任务看板行 (读写投影); 本 skill 是批量执行层 (归档+销 worktree+清看板)。

失败模式 (触发 → 一线修复 → 仍失败兜底)

与下方「反例黑名单」区别: 黑名单是不要做什么, 本表是 批量收尾跑起来卡壳时怎么办。

| 触发 | 一线修复 | 仍失败兜底 | | --- | --- | --- | | 某 task 收尾非 0 退出 (多为合并冲突) | 检脚本失败清单, 逐个转手动解冲突后 --apply 重跑 (幂等可重入) | 反复冲突解不开 → 硬停 该 task, 报给用户裁定 (改代码 / 弃分支), 禁当成功继续 | | 脏 / 未合并 worktree 被自动保留 | 提示用户先提交或合并该分支, 再重跑清理 | 用户明确弃这些改动 → 仍不强删, 让用户手动 git worktree remove --force, 本 skill 不代执行破坏性删 | | dry-run 与 --apply 间状态漂移 (期间新完成/新合并 task) | 重跑 dry-run 刷新清单再经 AskUserQuestion 确认 | 清单仍对不上 → 缩小范围逐 task finish 收尾, 禁按旧清单盲 apply | | --apply 部分成功、部分失败 | 已归档的不回滚 (幂等), 仅对失败 tid 重跑 | 重跑仍失败 → 列残留 tid 给用户, 标「待手动收尾」 | | 脚本不存在 (项目未跑 apply) | 提示用户先 /trellisx-apply 复制脚本到 .trellis/scripts/ | 用户暂不跑 → 本批量层不可用, 降级逐个 task.py finish 手工收尾 |

反例黑名单 (禁做)

| # | 反模式 | 为什么禁 | 替代 | | --- | --- | --- | --- | | 1 | 跳过 dry-run 直接 --apply | 破坏性操作未经确认 = 可能误销未合并 worktree | 先 dry-run → AskUserQuestion 确认 → 再 --apply | | 2 | 用纯文本"我将清理…"代替 AskUserQuestion | 确认必须用专门工具 | 经 AskUserQuestion 列 tid + worktree 路径 | | 3 | 把当前 active task 一起归档 | 销正在用的 worktree = 流程错误 | 脚本已排除 active; 禁手动绕过 | | 4 | 收尾失败 (冲突) 当成功继续 | 漏合丢提交 | 检失败清单, 转手动解冲突后重跑 | | 5 | 强删脏/未合并 worktree | 丢未提交/未合并改动 | 保留它们, 先提交/合并再清理 |