tidy

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/.

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.

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

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ộ.

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.

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):

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

   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).
1. 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.
2. 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).
3. 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.
4. 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.

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

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.

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ỏ.

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.