tidy

スキル：tidy

WHAT

目的とコンテキスト

• 目的： 膨れ上がった下書きとレンダー済みファイル（wiki/sources/draft/*.md + llmwiki/html/*.html）を整理して検証します。価値のある本質は wiki に PROMOTE し、完了した下書きは ARCHIVE（追跡対象のまま、削除しない）し、canonical は KEEP してから、RE-INDEX します。
• 使用するタイミング：
  • セッション開始時に 🧹 [tidy] draft/ có N file .md tầng gốc (> ngưỡng 10) を確認した場合 — フック session_start.py がユーザーに尋ねます。ユーザーが同意したら、このスキルを実行します。ユーザーが拒否したら、そのセッション中はスキップし、再度尋ねません。
  • draft/ または llmwiki/html/ が散らかって探しにくく、価値のある本質を失う心配があるときに、ユーザーが /tidy を直接呼び出した場合。
  • /lint のステップ 8c（docs-sprawl pulse）または medic のプローブ tidy が warn を報告した場合。
• 対象外： 下書きを削除しません。古いという理由だけで、現役の下書きを archive しません。すでに archive/ にあるファイルを「標準に合わせて修正」しません。

メンタルモデル

なぜ3層なのか（単に「マージ」するだけではない理由）：下書きの価値あるものは 決定／教訓／パターン であり、wiki に反映する必要があります（concept/ADR、移動され、コミットされ、インデックスに登録されます）。一方、実行済みの下書きとレンダー済みの HTML は履歴なので、archive に保管します（保持し、削除しません）。ツールが確定的に担当するのは、件数確認、分類、移動、インデックス作成です。内容を読み解いて昇格するのはエージェントの役割です。

draft/ + html/ → check (件数確認) → plan (KEEP · ARCHIVE · PROMOTE?) → エージェントが昇格 → apply (git mv で archive/<グループ>/ に移動) → 再インデックス → 検証 + コミット

入出力の契約

	フィールド	必須？	意味
入力	--threshold N / env OVERSTACK_DRAFT_THRESHOLD	いいえ（デフォルト 10）	ルート階層にある .md ファイル数のしきい値
入力	--keep-dates N	いいえ（デフォルト 2）	html レポートで保持する日付の数
入力	--root .	いいえ	下流に harness/ がない場合に使用します
出力	plan の表	はい	各ファイルの理由を添えた KEEP / ARCHIVE / PROMOTE?
出力	wiki 内の新しい ADR/concept	内容による	昇格された価値ある本質。## Origin を含みます
出力	archive/<proposals/superseded/analysis/reports>/ へのリネーム + インデックス	はい（apply 時）	git にはリネームとして記録され、削除ではありません

ルールと機能

• RULE-01 (MUST)：APPLY より先に PROMOTE します。 archive は現在追跡対象なので、後からでも昇格できますが、価値ある本質を誰にも知られないまま archive/ の下に埋もれさせないでください。
• RULE-02 (MUST)：Archive は移動であり、削除ではありません。 下書きを rm してはいけません。git mv で履歴を保持します（git log --follow）。
• RULE-03 (MUST)：status: proposed/open/implementing の下書きを archive する理由として、古さを挙げてはいけません。完了した status/task（または archive 済み SPEC に付随する PLAN/seq）のみ archive できます。停滞中の下書きを整理する場合は、担当者が判断して status を変更し、再実行します。
• RULE-04 (MUST)：canonical（overstack.html、index.html、wiki-graph.html、*-cheatsheet、*-health-dashboard、problem-tree、line-status）は絶対に archive しません。日付付きの html レポートは、直近の2つの日付を保持します（--keep-dates N）。それより古いものは archive します。html はレンダーなので、これは .md には適用しません。
• RULE-05 (MUST)：役割を明確にします。ツール = 件数確認／分類／移動／再インデックス（確定的、0 token）；エージェント = 昇格（内容の読み解き）。混同しません。
• 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/concept/index/log）、ローカルでの wiki-health/index_sync チェックの実行。

失敗時の境界

• check の終了コードが 3 の場合 = しきい値超過 → plan に進みます。しきい値未満で、ユーザーからの直接呼び出しでもない場合 → 停止し、整理するものはありません。
• 停滞中の下書き（status: proposed/open…）の場合 → 確認：ユーザーに続行するか却下するか尋ね、自動で archive しません。
• archive の移動先が .gitignore の対象の場合 → ツールは移動を拒否します（意図的な動作）。削除が必要な gitignore の行を出力し、そのファイルを blocked とします。
• wiki-health --fail-on broken または index_sync が赤の場合 → failed。コミット前に修正します。

HOW

メインワークフロー

ステップ	種類	入力	アクション	出力／終了条件	失敗時／次の処理
W01	決定的	draft/	チェック（0 トークン、ファイルに触れない）：tidy.py check	exit 3 = しきい値超過	しきい値未満 → ユーザーが明示的に呼び出さない限り停止
W02	決定的	draft + html	プラン（ドライラン）：tidy.py plan、理由の列をよく読む	KEEP／ARCHIVE／PROMOTE? の表	draft が保留中 → B01；古い内容のフラグ → B02
W03	判断	PROMOTE? の項目 + 判断が必要な ARCHIVE 項目	価値ある本質を持つものを、適用する前に wiki に PROMOTE する	ADR／concept + index + log	wiki にすでにある → archive のみ
W04	効果	plan	適用：tidy.py apply — git mv で archive に移動 + 再インデックス	rename + index	移動先が gitignored → B03
W05	決定的	worktree	検証 + commit：git status、wiki-health、index_sync	commit + log	エラー → 修正して W05 を繰り返す

各ステップの詳細（W01〜W05、ステップ 0〜4 の正確な情報源）：

0. チェック（0 トークン、ファイルに触れない）：

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

   Exit 3 = しきい値超過（デフォルトはルート階層の .md ファイル 10 個。サブディレクトリは対象外です。--threshold N または環境変数 OVERSTACK_DRAFT_THRESHOLD で変更できます）。
1. プラン（ドライラン）： python3 harness/scripts/tidy.py plan → 各ファイルの理由を添えた KEEP / ARCHIVE / PROMOTE? の表が表示されます。理由の列をよく読んでください。
   • OUTDATED — status done|implemented|… または task T-… đã done → draft は完了済みです → ARCHIVE。
   • ⏱ TREO — status proposed/open… → まだ有効です。古いというだけでは archive の理由になりません。整理する場合は、ユーザーに作業を続けるか reject するかを確認します（frontmatter の status: を変更して、再実行します）。
   • PROMOTE? = status も task もない draft です → エージェントが読んで判断します。
   • KEEP 対象の draft の下にある ↳ ⚠ nội dung có thể outdated = 引用先のファイルがなくなっている（claim-receipts）か、記述対象のコードが作成後に変更されています（stale.json の code-drift フラグ）。Status が有効でも内容が正しいとは限りません。コードと照らし合わせてから、（a）完了済みなら status を変更して archive、（b）作業中なら誤っている文を修正、（c）取りやめるなら rejected にするか need-review/ に移動します。誤検知（サンプルのパスなど）もあるため、結論を出す前に必ず読んでください。
2. 価値ある本質を持つものを wiki に PROMOTE する — 適用前に実施（エージェントが判断）：各 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 しません。
3. 適用： python3 harness/scripts/tidy.py apply — ARCHIVE グループを archive/<proposals|superseded|analysis|reports>/ に移動します（tracked ファイルは git mv を使用し、git には削除ではなく rename と認識されます）。以前に archive したファイルも整理し、再インデックスします（build-docs-index があれば実行、index_sync --fix、html/archive/INDEX.md）。
   • 移動先が .gitignore の対象の場合、ツールは tracked ファイルの移動を拒否し、削除する必要がある gitignore の行を表示します。これは意図された動作であり、エラーではありません。
4. 検証 + 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 が正常であることを確認します。ADR／新たに promote した concept と rename を含めて commit します。wiki/log.md に追記します。

分岐

ID	種類	条件	動作	スキップ／失敗	再開先
B01	条件付きで必須	plan に ⏱ TREO — status proposed/open… と表示される	保持します。整理する場合は、ユーザーに作業を続けるか reject するかを確認し、status: を変更して plan を再実行します	ユーザーが判断しない → KEEP	W02
B02	条件付きで必須	KEEP 対象の draft の下に ↳ ⚠ nội dung có thể outdated の行がある	コードと照らし合わせます：（a）完了済み → status を変更して archive、（b）作業中 → 誤っている文を修正、（c）取りやめ → rejected にするか need-review/ に移動	誤検知（サンプルのパス） → そのまま保持	W03
B03	リカバリー	移動先が .gitignore の対象のため、ツールが移動を拒否する	削除する必要がある gitignore の行をユーザーに伝えます。削除で回避してはいけません	ユーザーが削除しない → そのファイルはそのままにする	W04

検証と停止

必須：bash harness/tests/tidy-test.sh（下記の「必須テスト」）、wiki-health --fail-on broken が問題なし、index_sync が成功、git status に rename と archive/INDEX.md だけが表示されること。レビューが必要：PROMOTE の判断（エージェントによる読解）。W05 のコミット後に停止します。計画が変わらない限り、同じセッション内で apply を何度も繰り返さないでください。

例

• 成功例： セッション開始時に [tidy] draft/ có 57 file と表示され、ユーザーが同意 → 計画：40 ARCHIVE（status done）、4 PROMOTE?、13 KEEP → エージェントが wiki にまだない判断について ADR を 1 件作成 → tidy.py apply → git status には rename だけが表示される → wiki-health に問題なし → コミット。
• 境界／失敗例： status: proposed の draft が 3 か月前のもの → 計画では ⏱ TREO とし、アーカイブしない。作業を続けるか却下するかをユーザーに確認します。移動先の archive/reports/ が gitignore の対象 → apply はその追跡対象ファイルの移動を拒否し、削除が必要な gitignore の行を表示します。

必須テスト

bash harness/tests/tidy-test.sh — 11 件の assertion：しきい値は >10（サブディレクトリは数えない）、status done → archive、古い proposed → keep、gitignore 対象の移動先 → 移動しない、追跡対象の移動先 → git rename、循環が閉じると exit 0。