ysaa1/harness-workflow/cleanup

Knowledge Cleanup

使本次任务的记录与实际结果一致。完成、阻塞、放弃和交接都可整理，不要求先获得 ready 才能记录未完成工作。

流程

1. 明确本任务/轨道及其权威入口；无持久任务记录时可直接检查本次 diff。多个独立轨道可同时 active，不修改其他轨道来凑唯一工作面。
2. 只检查本次改变影响的 README、指令、接口文档、生成物和已有恢复记录。只有证据显示跨文档漂移或用户要求全量整理时扩大范围。
3. 清理本任务引入的代码遗留：死代码、未用导入和依赖、被替代的旧实现、孤儿脚本与过期生成物。删除以引用证据为准，删后跑针对性检查确认行为不变；会改变行为的清理转 implement 修复路径，不当作纯整理。
4. 轨道关闭（完成、放弃、换轨）时关轨道，同一 commit 内：删 .harness/index.md 的本轨道行和 tracks/<id>.md，把本轨道计划/Spec 里的非显然经验写进 lessons.md（没有就不写），删本轨道的计划与 Spec 文档（含未批准与放弃件；git 历史即归档，ADR 不删）。删文档前先确认改动已 commit 进主树，否则 git 里找不回来。轨道未关闭（阻塞、暂停、交接）时只改本轨道 tracks/<id>.md 的 Status:、Evidence:、Next:，不改 index.md，也不碰其他轨道的文件。格式与理由见 ../writing-for-agents/references/recovery_surface_policy.md。项目有 scripts/harness_lint.py 时提交前跑一次，修掉 ERROR（别的轨道仍链接被删文档时它会报断链，改指针或保留文档）。非 harness backend：把 tracker 原生状态翻到对应终态，缺件的步骤跳过。既有归档目录（docs/archive/ 类）的内容交用户裁决；untracked 文件不删，出口是补 commit 或补 .gitignore。
5. 清理本任务创建且已无用途的 scratch。未知归属或仍有用途的文件保留并说明；不因为 untracked、旧日期或临时命名就删除。
6. 生成物通过现有生成器更新，仅在输入变化时重建。无差异可零修改完成。本次新踩的坑（环境、流程、依赖）写进项目恢复面的 lessons：归入对应主题 ##，每条「触发 → 坑 → 正确做法」；harness backend 而 lessons.md 不存在时随首次落笔创建，失效条目随手删。

环境改进（与 lessons 同一步）：先读仓库现有检查入口（check 脚本、lint/typecheck 命令、pre-commit、CI），再问——本次失误若是机械性的（固定语法模式、禁用 API、导入形态、文件位置规则），优先提议确定性检查（项目 linter 自定义规则、pre-commit、CI 任务或 check 脚本断言），不写成文字规则；只有判断级问题才进规范文档或 lessons。已存在但未接线或已坏的检查本身就是发现，不重造。另扫五类候选：导航（找文件慢→加导航指针）、持久指令膨胀（AGENTS.md 里该迁去规范/检查的规则、不改变行为的空规则）、工具开销（昂贵调用可精简）、信息获取（缺日志或只读访问）、无正确测试 seam（来自 diagnose）。候选只在报告中按严重度列出；落地检查需用户授权，hook 只在用户明确要求时才装。零候选记「无新增」。

1. 报告任务状态、修改/归档、保留事项及恢复入口。不得把 cleanup 完成写成原任务已完成。

按需读取

• 计划过期：references/doc-shelves.md。
• 临时文件归属：references/entropy-checklist.md。
• 交接：references/handoff-hygiene.md。
• 领域风险：../review/references/cross-cutting-anti-patterns.md（未安装 review 时跳过此参考，按本文件流程与证据规则执行）。

Recommended next skill

• 整理完成：结束。
• 仍有已授权行为修改：implement；未知失败：diagnose。
• 用户显式要求全仓 Python 死代码清理：remove-deadcode-py；其他生态直接用对应工具（JS/TS knip、Go deadcode、Rust cargo-machete）。
• 用户显式要求全仓对账/盘点/大扫除，或发现跨文档漂移、用户要求全量整理：sweep。
• 新增工作超出任务：记录后续事项，不自动执行。