| name | trellisx-cleanup |
| description | 🧹 批量收尾 —— 一次清理/归档/收尾**全部**已完成 task。三件事: ① 清理所有已合并的 worktree ② 归档所有已完成的任务 ③ 清理 task.md 看板的已完成行。完成判定 = completed ∪ merged (并集), 当前 active task 永不纳入。**强制 dry-run → 用户确认 → --apply 执行** 三段护栏, worktree 销毁沿用安全判据 (脏/未合并自动保留, 不丢提交) |
| disable-model-invocation | true |
| argument-hint | [--apply] [--days N] |
| arguments | [缺省 = dry-run 只报告; --apply = 执行; --days N = 看板已完成行清理阈值, 默认 0 全删] |
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, 禁用"建议清理"软措辞替代确认工具。
- dry-run (默认, 只读): 不带
--apply 跑, 打印将归档的 task、将销的 worktree、将保留的 worktree (脏/未合并)、将删的看板行阈值。不改任何状态。
python3 .trellis/scripts/trellisx-cleanup.py
- 确认: 把 dry-run 清单经 AskUserQuestion 工具呈给用户 (列出 tid + worktree 路径), 用户批准才进第 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 | 丢未提交/未合并改动 | 保留它们, 先提交/合并再清理 |
