tidy

Skill：tidy

WHAT

目的与上下文

• **目的：**整理并验证草稿库和渲染文件（wiki/sources/draft/*.md + llmwiki/html/*.html），当它们膨胀时：将有价值的内容 PROMOTE 到 wiki，ARCHIVE 已完成的草稿（保留在版本控制中，不删除），KEEP 规范文件，然后 RE-INDEX。
• 触发条件（何时使用）：
  • 会话开始时看到 🧹 [tidy] draft/ có N file .md tầng gốc (> ngưỡng 10) — session_start.py hook 会询问用户；用户同意 → 运行此 skill。用户拒绝 → 跳过，本次会话不再询问。
  • 用户发现 draft/ 或 llmwiki/html/ 杂乱、难以查找，担心有价值的内容丢失时，自行调用 /tidy。
  • /lint 第 8c 步（docs-sprawl pulse）或 medic probe tidy 报告 warn。
• **非目标：**不删除草稿，不仅仅因为草稿较旧就归档仍在使用的草稿，也不“修正”已位于 archive/ 中的文件，使其符合规范。

心智模型

为什么要分 3 层（不只是“合并”）：草稿中有价值的内容是决策 / 经验教训 / 模式——它们必须进入 wiki（概念/ADR，可追溯 + 已提交 + 已索引）。而已执行完毕的草稿及其 HTML 渲染文件属于历史记录 → 归档（保留，不删除）。工具负责确定性地计数 + 分类 + 移动 + 索引；阅读理解并提升内容是 Agent 的工作。

draft/ + html/ → check（计数）→ plan（KEEP · ARCHIVE · PROMOTE?）→ Agent 提升内容 → apply（git mv 到 archive/<groups>/）→ re-index → 验证 + 提交。

输入和输出约定

	字段	必填？	含义
输入	--threshold N / 环境变量 OVERSTACK_DRAFT_THRESHOLD	否（默认值为 10）	顶层 .md 文件数量阈值
输入	--keep-dates N	否（默认值为 2）	保留的 HTML 报告日期数
输入	--root .	否	下游没有 harness/ 时使用
输出	计划表	是	为每个文件列出 KEEP / ARCHIVE / PROMOTE? 及原因
输出	wiki 中的新 ADR/概念	视内容而定	已提升的有价值内容，包含 ## Origin
输出	重命名到 archive/<proposals/superseded/analysis/reports>/ + 索引	是（应用时）	git 识别为重命名，而非删除

规则和能力

• RULE-01（MUST）：**先 PROMOTE，再 APPLY。**归档现在受版本控制，因此之后仍可提升内容，但不要让有价值的内容埋在 archive/ 中而无人知晓。
• RULE-02（MUST）：**归档 = 移动，不删除。**绝不 rm 草稿；使用 git mv 保留历史记录（git log --follow）。
• RULE-03（MUST）：草稿仍处于 status: proposed/open/implementing 时，不能仅因时间久远就归档。只有状态/任务已完成（或随已归档 SPEC 的 PLAN/seq）才能归档。要清理悬而未决的草稿 → 由用户决定并更改状态，然后重新运行。
• RULE-04（MUST）：规范文件（overstack.html、index.html、wiki-graph.html、*-cheatsheet、*-health-dashboard、problem-tree、line-status）绝不归档。带日期的 HTML 报告：保留最近的 2 个日期（--keep-dates N），更早的归档——这是针对 HTML 渲染文件的规则，不适用于 .md。
• RULE-05（MUST）：职责明确：工具 = 计数/分类/移动/重新索引（确定性，0 token）；Agent = 提升内容（阅读理解）。不可混淆。
• RULE-06（MUST）：新的 wiki 条目必须包含 ## Origin + frontmatter type（R2/R9）；更新 wiki/index.md + wiki/log.md（R3）。
• RULE-07（MUST）：Validator R7/R9/R18 和 wiki-health/index_sync 忽略 archive/（已冻结的草稿）——不要“修正”archive 中的文件，使其符合规范，它们是历史记录。
• 能力：读取 draft/html + frontmatter；使用 git 移动文件（受版本控制的重命名）；写入 wiki（ADR/概念/索引/日志）；在本地运行 wiki-health/index_sync 检查。

失败边界

• check 退出码为 3 = 超过阈值 → 继续执行 plan；低于阈值且用户没有主动调用 → 停止，无需整理。
• 草稿悬而未决（status: proposed/open…）→ 澄清：询问用户是继续处理还是拒绝，不要自行归档。
• 归档目标被 .gitignore 忽略 → 工具拒绝移动（有意为之），打印需要移除的 gitignore 规则 → 该文件被 阻止处理。
• wiki-health --fail-on broken 或 index_sync 报错 → 失败，提交前先修复。

HOW

主工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	确定性	draft/	检查（0 token，不触碰文件）：tidy.py check	exit 3 = 超过阈值	未超过阈值 → 停止，除非用户主动调用
W02	确定性	draft + html	计划（dry-run）：tidy.py plan，仔细阅读理由列	KEEP/ARCHIVE/PROMOTE? 表格	draft 悬而未决 → B01；标记 outdated → B02
W03	判断	PROMOTE? 项 + 已决定的 ARCHIVE 项	在 apply 之前，先将有价值的实质内容 PROMOTE 到 wiki	ADR/concept + index + log	wiki 中已有 → 只 archive
W04	执行	plan	Apply：tidy.py apply — 用 git mv 移入 archive + 重新索引	rename + index	目标被 gitignore → B03
W05	确定性	worktree	验证并提交：git status、wiki-health、index_sync	commit + log	有红项 → 修复，重复 W05

各步骤的详细说明（W01–W05、第 0–4 步的权威信息）：

0. 检查（0 token，不触碰文件）：

   python3 harness/scripts/tidy.py check          # downstream không có harness/: python3 ~/.claude/harness/harness/scripts/tidy.py check --root .
   

   Exit 3 = 超过阈值（默认根目录下 10 个 .md 文件，不计子目录；可通过 --threshold N 或 env OVERSTACK_DRAFT_THRESHOLD 修改）。
1. 计划（dry-run）： python3 harness/scripts/tidy.py plan → KEEP / ARCHIVE / PROMOTE? 表格，并附每个文件的理由。仔细阅读理由列：
   • OUTDATED — status done|implemented|… 或 task T-… 已 done → 草稿已完成 → ARCHIVE。
   • ⏱ TREO — status proposed/open… → 仍然有效，不能仅因时间久就 archive；若要清理，询问用户是继续处理还是 reject（修改 frontmatter 中的 status:，然后重新运行）。
   • PROMOTE? = draft 没有 status，也没有 task → 由 Agent 阅读后决定。
   • 某个应保留的 draft 下方出现 ↳ ⚠ nội dung có thể outdated = 它引用的文件已失效（claim-receipts），或它提到的代码在写完后发生了变化（stale.json 中的 code-drift 标记）。Status 仍有效不代表内容仍然正确：对照代码，然后（a）已完成 → 修改 status 并 archive，（b）仍在进行 → 修正错误的句子，（c）不再处理 → 标记为 rejected 或移至 need-review/。可能存在误报（例如示例路径），因此必须先阅读再下结论。
2. 在 apply 之前，先将有价值的实质内容 PROMOTE 到 wiki（由 Agent 判断）：对于每个 PROMOTE? 项，以及每个似乎包含 wiki 中尚未记录的决策/经验的 ARCHIVE 项 → 写入 llmwiki/wiki/sources/adr/ADR-NNN-<slug>.md（决策）或 llmwiki/wiki/concepts/<slug>.md（概念），使用正确的 frontmatter type:，并在 ## Origin 中指向 draft；更新 wiki/index.md + wiki/log.md。wiki 中已有 → 只 archive。不要 promote 无关紧要的内容（进度报告、重复的渲染内容）。
3. Apply： python3 harness/scripts/tidy.py apply — 将 ARCHIVE 组移至 archive/<proposals|superseded|analysis|reports>/（已跟踪的文件 → git mv，git 会识别为 rename 而非 delete），整理此前已 archive 的所有文件，然后重新索引（若存在 build-docs-index，则运行 index_sync --fix 和 html/archive/INDEX.md）。
   • 若目标被 .gitignore 忽略，工具会拒绝移动已跟踪的文件（移动 = 从仓库删除），并打印需要移除的 gitignore 条目。这是有意为之，并非错误。
4. 验证并提交： git status 只应显示 rename/archive/INDEX.md；python3 harness/scripts/wiki-health.py --wiki-dir llmwiki/wiki --fail-on broken 检查通过（指向 archive/ 中 stem 的 wikilink 会解析为 resolved-frozen，不算 broken）；index_sync 检查通过。提交内容包括新 promote 的 ADR/concept 和各项 rename。追加更新 wiki/log.md。

分支

ID	类型	守卫条件	行为	跳过 / 失败	汇合
B01	conditional_required	plan 报告 ⏱ TREO — status proposed/open…	保留；若要清理，询问用户是继续处理还是 reject，修改 status: 后重新运行 plan	用户未决定 → KEEP	W02
B02	conditional_required	某个应保留的 draft 下方出现 ↳ ⚠ nội dung có thể outdated	对照代码：（a）已完成 → 修改 status + archive，（b）仍在进行 → 修正错误的句子，（c）不再处理 → 标记为 rejected 或移至 need-review/	误报（例如示例路径）→ 保持原样	W03
B03	recovery	工具因目标被 .gitignore 忽略而拒绝移动	告知用户需要移除的 gitignore 条目；不要绕过检查直接删除	用户不移除 → 文件保持原位	W04

验证与停止

必须满足：bash harness/tests/tidy-test.sh（见下方“确定性测试”）、wiki-health --fail-on broken 无问题、index_sync 通过、git status 仅显示重命名/archive/INDEX.md。需要审查：决定是否 PROMOTE（由 Agent 阅读理解）。在 W05 提交后停止；如果计划没有变化，不要在一个会话中反复执行 apply。

示例

• 正例： 会话开始时报告 [tidy] draft/ có 57 file，用户同意 → 计划：40 个 ARCHIVE（status done）、4 个 PROMOTE?、13 个 KEEP → Agent 为 wiki 中尚无记录的决定编写 1 份 ADR → tidy.py apply → git status 仅显示重命名 → wiki-health 无问题 → 提交。
• 边界/失败： draft 中的 status: proposed 已有 3 个月 → 计划标记为 ⏱ TREO，不归档；询问用户是继续处理还是拒绝。目标 archive/reports/ 被 gitignore 忽略 → apply 拒绝移动该已跟踪文件，并输出需要移除的 gitignore 规则。

确定性测试

bash harness/tests/tidy-test.sh — 11 项断言：阈值 >10（不计子目录）、status done → archive、过期 proposed → keep、目标被 gitignore 忽略 → 不移动、目标已跟踪 → git rename、闭环后退出码为 0。