tidy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: tidy

WHAT

Purpose và context

目的与上下文

Purpose: dọn + validate kho nháp và render (
```
wiki/sources/draft/*.md
```
+
```
llmwiki/html/*.html
```
) khi phình to: PROMOTE bản chất quý lên wiki, ARCHIVE nháp đã xong (tracked, không xoá), KEEP canonical, rồi RE-INDEX.
Trigger (when to use):
- Đầu phiên thấy
```
🧹 [tidy] draft/ có N file .md tầng gốc (> ngưỡng 10)
```
  — hook
```
session_start.py
```
  hỏi user; user ĐỒNG Ý → chạy skill này. User TỪ CHỐI → bỏ qua, không hỏi lại trong phiên.
- User tự gọi
```
/tidy
```
  khi thấy
```
draft/
```
  hoặc
```
llmwiki/html/
```
  lộn xộn, khó tìm, sợ mất bản chất quý.
- ```
/lint
```
  bước 8c (docs-sprawl pulse) hoặc
```
medic
```
  probe
```
tidy
```
  báo warn.
Non-goals: không xoá nháp, không archive draft còn sống chỉ vì cũ, không "sửa cho đúng chuẩn" file đã nằm trong
```
archive/
```
.

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

Mental model

思维模型

Vì sao 3 tầng (không chỉ "merge"): Cái QUÝ trong nháp là quyết định / bài học / pattern — nó phải lên wiki (concept/ADR, travel + được commit + được index). Còn nháp đã thi hành xong và render html là lịch sử → archive (giữ, không xoá). Tool tất định lo đếm + phân loại + dời + index; phần đọc-hiểu để promote là việc của agent.

draft/ + html/ → check (đếm) → plan (KEEP · ARCHIVE · PROMOTE?) → agent promote → apply (git mv vào archive/<nhóm>/) → re-index → verify + commit

为什么是三层（不只是“合并”）：草稿中的精华是决策 / 经验 / pattern——它必须进入 wiki（concept/ADR，完成 travel + commit + index）。已完成并 render 为 html 的草稿属于历史 → archive（保留，不删除）。确定性工具负责计数 + 分类 + 移动 + index；需要阅读、理解并执行 promote 的部分由 Agent 负责。

draft/ + html/ → check（计数）→ plan（KEEP · ARCHIVE · PROMOTE?）→ Agent promote → apply（通过 git mv 移入 archive/<组>/）→ re-index → verify + commit

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	`--threshold N` / env `OVERSTACK_DRAFT_THRESHOLD`	không (mặc định 10)	ngưỡng số file `.md` tầng gốc
In	`--keep-dates N`	không (mặc định 2)	số mốc ngày html report giữ lại
In	`--root .`	không	dùng khi downstream không có `harness/`
Out	bảng plan	có	KEEP / ARCHIVE / PROMOTE? kèm lý do từng file
Out	ADR/concept mới trong wiki	theo nội dung	bản chất quý đã promote, có `## Origin`
Out	rename vào `archive/<proposals/superseded/analysis/reports>/` + index	có (khi apply)	git thấy rename, không delete

	字段	是否必需？	含义
输入	`--threshold N` / 环境变量 `OVERSTACK_DRAFT_THRESHOLD`	否（默认 10）	根层级 `.md` 文件数量的阈值
输入	`--keep-dates N`	否（默认 2）	保留的带日期 html report 数量
输入	`--root .`	否	当 downstream 环境中没有 `harness/` 时使用
输出	plan 表	是	包含每个文件的 KEEP / ARCHIVE / PROMOTE? 及原因
输出	wiki 中新建的 ADR/concept	根据内容而定	已 promote 的精华，包含 `## Origin`
输出	重命名至 `archive/<proposals/superseded/analysis/reports>/` + index	是（apply 时）	git 将其识别为 rename，而非 delete

Rules và capabilities

规则与能力

RULE-01 (MUST): PROMOTE trước APPLY. Archive giờ TRACKED nên promote-sau vẫn làm được, nhưng đừng để bản chất chôn dưới
```
archive/
```
mà không ai biết.
RULE-02 (MUST): Archive = DỜI, KHÔNG XOÁ. Không bao giờ
```
rm
```
nháp;
```
git mv
```
giữ history (
```
git log --follow
```
).
RULE-03 (MUST): Tuổi không phải lý do archive một draft còn
```
status: proposed/open/implementing
```
. Chỉ status/task đã xong (hoặc PLAN/seq đi theo SPEC đã archive) mới archive. Muốn dọn draft treo → người quyết, đổi status, chạy lại.
RULE-04 (MUST): Canonical (
```
overstack.html
```
,
```
index.html
```
,
```
wiki-graph.html
```
,
```
*-cheatsheet
```
,
```
*-health-dashboard
```
,
```
problem-tree
```
,
```
line-status
```
) không bao giờ archive. Html report có ngày: giữ 2 mốc ngày gần nhất (
```
--keep-dates N
```
), cũ hơn archive — html là render, không áp cho
```
.md
```
.
RULE-05 (MUST): Vai rõ: tool = đếm/phân loại/dời/re-index (tất định, 0 token); agent = promote (đọc-hiểu). Không lẫn.
RULE-06 (MUST): Wiki entry mới phải có
```
## Origin
```
+ frontmatter
```
type
```
(R2/R9); cập nhật
```
wiki/index.md
```
+
```
wiki/log.md
```
(R3).
RULE-07 (MUST): Validator R7/R9/R18 và
```
wiki-health
```
/
```
index_sync
```
bỏ qua
archive/
(nháp đông cứng) — đừng "sửa cho đúng chuẩn" file trong archive, chúng là lịch sử.
Capabilities: đọc draft/html + frontmatter; dời file bằng git (tracked rename); ghi wiki (ADR/concept/index/log); chạy kiểm wiki-health/index_sync cục bộ.

RULE-01（必须）：先 PROMOTE，再 APPLY。 Archive 目前是 TRACKED，因此延后 promote 仍然可行，但不要让精华被埋在
```
archive/
```
下而无人知晓。
RULE-02（必须）：Archive = 移动，不删除。 绝不要使用
```
rm
```
删除草稿；
```
git mv
```
会保留 history（
```
git log --follow
```
）。
RULE-03（必须）：草稿仍为
status: proposed/open/implementing
时，年龄不能成为 archive 的理由。只有 status/task 已完成（或 PLAN/seq 跟随已 archive 的 SPEC）时才能 archive。若要清理悬而未决的 draft，需要由用户决定，修改 status，然后重新运行。
RULE-04（必须）：Canonical（
```
overstack.html
```
、
```
index.html
```
、
```
wiki-graph.html
```
、
```
*-cheatsheet
```
、
```
*-health-dashboard
```
、
```
problem-tree
```
、
```
line-status
```
）永不 archive。带日期的 html report：保留最近 2 个日期节点（
```
--keep-dates N
```
），更早的则 archive——html 是 render，不适用于
```
.md
```
。
RULE-05（必须）：职责明确：工具 = 计数/分类/移动/re-index（确定性，0 token）；Agent = promote（阅读并理解）。不得混淆。
RULE-06（必须）：新建的 Wiki entry 必须包含
```
## Origin
```
+ frontmatter
```
type
```
（R2/R9）；更新
```
wiki/index.md
```
+
```
wiki/log.md
```
（R3）。
RULE-07（必须）：Validator R7/R9/R18 和
```
wiki-health
```
/
```
index_sync
```
必须跳过
archive/
（已冻结的草稿）——不要“修正到符合规范” archive 中的文件，它们属于历史。
能力：读取 draft/html + frontmatter；通过 git 移动文件（tracked rename）；写入 wiki（ADR/concept/index/log）；在本地运行 wiki-health/index_sync 检查。

Failure boundaries

失败边界

```
check
```
exit 3 = vượt ngưỡng → đi tiếp plan; dưới ngưỡng và user không tự gọi → dừng, không có gì dọn.
Draft treo (
```
status: proposed/open…
```
) → clarify: hỏi user làm-tiếp hay reject, không tự archive.
Đích archive bị
```
.gitignore
```
→ tool từ chối dời (chủ ý), in dòng gitignore cần bỏ → blocked cho file đó.
```
wiki-health --fail-on broken
```
hoặc
```
index_sync
```
đỏ → failed, sửa trước khi commit.

```
check
```
exit 3 = 超出阈值 → 继续进入 plan；低于阈值且用户未手动调用 → 停止，不做任何清理。
悬而未决的 draft（
```
status: proposed/open…
```
）→ clarify：询问用户是继续还是 reject，不得自行 archive。
Archive 目标被
```
.gitignore
```
→ 工具拒绝移动（有意为之），并打印需要移除的 gitignore 行 → 对该文件而言为 blocked。
```
wiki-health --fail-on broken
```
或
```
index_sync
```
为红色 → failed，commit 前先修复。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	`draft/`	Check (0 token, không đụng file): `tidy.py check`	exit 3 = vượt ngưỡng	dưới ngưỡng → dừng trừ khi user tự gọi
W02	deterministic	draft + html	Plan (dry-run): `tidy.py plan` , đọc kỹ cột lý do	bảng KEEP/ARCHIVE/PROMOTE?	draft treo → B01; cờ outdated → B02
W03	judgment	mục PROMOTE? + ARCHIVE có quyết định	PROMOTE bản chất quý vào wiki TRƯỚC khi apply	ADR/concept + index + log	đã có trong wiki → chỉ archive
W04	effect	plan	Apply: `tidy.py apply` — git mv vào archive + re-index	rename + index	đích gitignored → B03
W05	deterministic	worktree	Verify + commit: `git status` , `wiki-health` , `index_sync`	commit + log	đỏ → sửa, lặp W05

Chi tiết từng bước (nguồn chân lý cho W01–W05, bước 0–4):

Check (0 token, không đụng file):

bash

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

Exit 3 = vượt ngưỡng (mặc định 10 file

.md

tầng gốc, thư mục con không tính; đổi bằng

--threshold N

hoặc env

OVERSTACK_DRAFT_THRESHOLD

Plan (dry-run):
```
python3 harness/scripts/tidy.py plan
```
→ bảng KEEP / ARCHIVE / PROMOTE? kèm lý do từng file. Đọc kỹ cột lý do:
- ```
OUTDATED — status done|implemented|…
```
  hoặc
```
task T-… đã done
```
  → nháp đã xong → ARCHIVE.
- ```
⏱ TREO — status proposed/open…
```
  → còn sống, tuổi không phải lý do archive; muốn dọn thì hỏi user quyết làm-tiếp hay reject (đổi
```
status:
```
  trong frontmatter rồi chạy lại).
- ```
PROMOTE?
```
  = draft không status, không task → agent đọc rồi quyết.
- ```
↳ ⚠ nội dung có thể outdated
```
  dưới một draft GIỮ = file nó trích dẫn đã chết (claim-receipts) hoặc code nó nói tới đã đổi sau khi viết (cờ
```
code-drift
```
  trong
```
stale.json
```
  ). Status còn sống không có nghĩa là nội dung còn đúng: đối chiếu với code, rồi (a) đã làm xong → đổi status và archive, (b) còn làm → sửa đúng câu sai, (c) bỏ →
```
rejected
```
  hoặc dời
```
need-review/
```
  . Có dương tính giả (đường dẫn ví dụ), nên phải đọc trước khi kết luận.
PROMOTE bản chất QUÝ vào wiki — làm TRƯỚC khi apply (phán đoán của agent): với mỗi mục
```
PROMOTE?
```
và mỗi mục ARCHIVE có vẻ chứa quyết định/bài học chưa có trong wiki → viết
```
llmwiki/wiki/sources/adr/ADR-NNN-<slug>.md
```
(quyết định) hoặc
```
llmwiki/wiki/concepts/<slug>.md
```
(khái niệm), đúng frontmatter
```
type:
```
+
```
## Origin
```
trỏ draft; cập nhật
```
wiki/index.md
```
+
```
wiki/log.md
```
. Đã có trong wiki → chỉ archive. Không promote thứ tầm thường (report tiến độ, render trùng).
Apply:
```
python3 harness/scripts/tidy.py apply
```
— dời nhóm ARCHIVE vào
```
archive/<proposals|superseded|analysis|reports>/
```
(file tracked →
```
git mv
```
, git thấy rename không delete), sắp xếp cả file đã archive từ trước, rồi re-index (
```
build-docs-index
```
nếu có,
```
index_sync --fix
```
,
```
html/archive/INDEX.md
```
).
- Tool từ chối dời file tracked khi đích bị
  .gitignore
  (dời = xoá khỏi repo) và in dòng gitignore cần bỏ. Đây là chủ ý, không phải lỗi.
Verify + commit:
```
git status
```
chỉ thấy rename/
```
archive/INDEX.md
```
;
```
python3 harness/scripts/wiki-health.py --wiki-dir llmwiki/wiki --fail-on broken
```
sạch (wikilink trỏ stem trong archive/ = resolved-frozen, không broken);
```
index_sync
```
xanh. Commit gồm ADR/concept mới promote + các rename. Append
```
wiki/log.md
```
.

步骤	类型	输入	操作	输出/退出码	失败/下一步
W01	确定性	`draft/`	Check（0 token，不接触文件）： `tidy.py check`	exit 3 = 超出阈值	低于阈值 → 停止，除非用户手动调用
W02	确定性	draft + html	Plan（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 + re-index	rename + index	目标被 gitignore → B03
W05	确定性	worktree	Verify + commit： `git status` 、 `wiki-health` 、 `index_sync`	commit + log	红色 → 修复，重复 W05

以下各步骤的详细信息（W01–W05 的真实来源，对应步骤 0–4）：

Check（0 token，不接触文件）：

bash

python3 harness/scripts/tidy.py check          # downstream 没有 harness/ 时：python3 ~/.claude/harness/harness/scripts/tidy.py check --root .

Exit 3 = 超出阈值（默认 10 个根层级

.md

文件，子目录不计入；使用

--threshold N

或环境变量

OVERSTACK_DRAFT_THRESHOLD

修改）。

Plan（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:
```
  ，然后重新运行 plan）。
- ```
PROMOTE?
```
  = draft 没有 status，也没有 task → 由 Agent 阅读后决定。
- 某个 KEEP 草稿下方的
```
↳ ⚠ nội dung có thể outdated
```
  表示它引用的内容已经失效（claim-receipts），或其描述的代码在撰写后已经改变（
```
stale.json
```
  中的
```
code-drift
```
  标记）。status 仍然活跃并不代表内容仍然正确：应与代码核对，然后：(a) 已完成 → 修改 status 并 archive；(b) 仍在进行 → 修正错误的陈述；(c) 放弃 → 设置为
```
rejected
```
  或移至
```
need-review/
```
  。可能存在假阳性（例如示例路径），因此必须阅读后再下结论。
将精华 PROMOTE 到 wiki——在 apply 之前执行（由 Agent 判断）： 对于每个
```
PROMOTE?
```
项，以及每个包含尚未收录到 wiki 的决策/经验的 ARCHIVE 项 → 写入
```
llmwiki/wiki/sources/adr/ADR-NNN-<slug>.md
```
（决策）或
```
llmwiki/wiki/concepts/<slug>.md
```
（概念），使用正确的 frontmatter
```
type:
```
+ 指向 draft 的
```
## Origin
```
；更新
```
wiki/index.md
```
+
```
wiki/log.md
```
。若 wiki 中已存在 → 只 archive。不要 promote 琐碎内容（进度 report、重复 render）。
Apply：
```
python3 harness/scripts/tidy.py apply
```
——将 ARCHIVE 组移入
```
archive/<proposals|superseded|analysis|reports>/
```
（tracked 文件 →
```
git mv
```
，git 将其识别为 rename 而非 delete），同时重新整理此前已 archive 的文件，然后 re-index（若存在则运行
```
build-docs-index
```
，运行
```
index_sync --fix
```
，并更新
```
html/archive/INDEX.md
```
）。
- 工具拒绝移动目标被
  .gitignore
  覆盖的 tracked 文件（移动意味着从 repo 中删除），并打印需要移除的 gitignore 行。这是有意设计，不是错误。
Verify + commit：
```
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
```
应为绿色。Commit 包含新 promote 的 ADR/concept + 各项 rename。追加
```
wiki/log.md
```
。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	plan báo `⏱ TREO — status proposed/open…`	giữ; muốn dọn thì hỏi user làm-tiếp hay reject, đổi `status:` rồi chạy lại plan	user không quyết → KEEP	W02
B02	conditional_required	dòng `↳ ⚠ nội dung có thể outdated` dưới draft GIỮ	đối chiếu code: (a) xong → đổi status + archive, (b) còn làm → sửa đúng câu sai, (c) bỏ → `rejected` hoặc dời `need-review/`	dương tính giả (đường dẫn ví dụ) → giữ nguyên	W03
B03	recovery	tool từ chối dời vì đích bị `.gitignore`	báo user dòng gitignore cần bỏ; không lách bằng xoá	user không bỏ → file đó ở yên	W04

ID	类型	守卫条件	行为	跳过/失败	汇合点
B01	条件必需	plan 报告 `⏱ TREO — status proposed/open…`	保留；如需清理，询问用户是继续还是 reject，修改 `status:` 后重新运行 plan	用户未决定 → KEEP	W02
B02	条件必需	KEEP 草稿下方出现 `↳ ⚠ nội dung có thể outdated`	与代码核对：(a) 已完成 → 修改 status + archive；(b) 仍在进行 → 修正错误的陈述；(c) 放弃 → `rejected` 或移至 `need-review/`	假阳性（例如示例路径）→ 保持不变	W03
B03	恢复	工具因目标被 gitignore 而拒绝移动	向用户报告需要移除的 gitignore 行；不得通过删除绕过	用户不移除 → 该文件保持原位	W04

Validation và stopping

验证与停止条件

Tất định:

bash harness/tests/tidy-test.sh

(mục Test tất định dưới),

wiki-health --fail-on broken

sạch,

index_sync

xanh,

git status

chỉ thấy rename/

archive/INDEX.md

. Cần review: quyết định PROMOTE (agent đọc-hiểu). Dừng sau W05 commit; không lặp apply nhiều lần trong một phiên nếu plan không đổi.

确定性验证：

bash harness/tests/tidy-test.sh

（见下方“确定性测试”）、

wiki-health --fail-on broken

无异常、

index_sync

为绿色，且

git status

仅显示 rename/

archive/INDEX.md

。需要审核：PROMOTE 决策（由 Agent 阅读并理解）。在 W05 commit 后停止；如果 plan 没有变化，不应在同一会话中多次执行 apply。

Examples

示例

Positive: đầu phiên báo
```
[tidy] draft/ có 57 file
```
, user đồng ý → plan: 40 ARCHIVE (status done), 4 PROMOTE?, 13 KEEP → agent viết 1 ADR cho quyết định chưa có trong wiki →
```
tidy.py apply
```
→
```
git status
```
chỉ thấy rename →
```
wiki-health
```
sạch → commit.
Boundary/failure: draft
```
status: proposed
```
3 tháng tuổi → plan đánh
```
⏱ TREO
```
, KHÔNG archive; hỏi user làm-tiếp hay reject. Đích
```
archive/reports/
```
bị gitignore → apply từ chối dời file tracked đó và in dòng gitignore cần bỏ.

正向示例： 会话开始时提示
```
[tidy] draft/ có 57 file
```
，用户同意 → plan：40 ARCHIVE（status done）、4 PROMOTE?、13 KEEP → Agent 为 wiki 中尚不存在的决策撰写 1 篇 ADR →
```
tidy.py apply
```
→
```
git status
```
只显示 rename →
```
wiki-health
```
干净 → commit。
边界/失败： 一个
```
status: proposed
```
且已有 3 个月的 draft → plan 标记
```
⏱ TREO
```
，不 archive；询问用户是继续还是 reject。
```
archive/reports/
```
目标被 gitignore → apply 拒绝移动该 tracked 文件，并打印需要移除的 gitignore 行。

Test tất định

确定性测试

bash harness/tests/tidy-test.sh

— 11 assertion: ngưỡng

>10

(thư mục con không tính), status done → archive, proposed cũ → keep, đích gitignored → không dời, đích tracked → git rename, vòng khép về exit 0.

bash harness/tests/tidy-test.sh

——11 项 assertion：阈值

>10

（子目录不计入）、status done → archive、proposed 且过旧 → keep、目标被 gitignore → 不移动、目标为 tracked → git rename、闭环至 exit 0。