plan-archive

/plan-archive — 完了した Plan をアーカイブする

plans/active/ 内の完了した plan を plans/completed/ に移動し、検証結果を追記します。

---

Step 1：アーカイブする Plan を見つける

引数（ファイル名またはパス）が渡された場合は、それをそのまま使用します。 それ以外の場合は、plans/active/ 内のすべての .md を一覧表示します：

ls plans/active/*.md 2>/dev/null

複数ある場合は、mtime 順に並べ、どれを選ぶかユーザーに尋ねます。 1 つだけの場合は、そのまま使用します。 ディレクトリが存在しない、または空の場合は、「アーカイブする plan が見つかりません」と出力して終了します。

---

Step 2：Plan の内容を読み取る

対象の plan ファイルを読み取り、以下を確認します：

• 実装ステップのセクションがあるか。canonical 形式（/design が生成し、plan_runner.py が解析する形式）の step は、- [ ] **S<phase>.<num>** — <title> という S-code 項目です。phase は任意の ### 見出しです（parser は ^###\s+(.+)$）。慣例では ### Phase N — <title> と記述しますが、コロンでもダッシュでも構いません。旧 plan には ## Phase X / ### Step X.Y という見出し形式もあるため、どちらも認識します
• ## 驗證 または ## Verification セクションがあるか
• ## Industry & Standards Reference セクションがあるか

plan 内のすべての step を追跡リストとして列挙し、それぞれの完了状態をマークします。まず canonical S-code 形式（- [ ] **S1.1** — <title>。phase は直前にある ### 見出し）を取得し、見つからない場合は旧見出し形式（## Phase X / ### Step X.Y）にフォールバックします。どちらの形式でも空のリストになった場合は、そこで停止してユーザーに確認してください。「step が 0 件」として続行してはいけません。空のリストでは Step 3 の完了率に意味がなくなるためです。

完了率の分母はこのリストの長さ（plan 内の実際の step 数）であり、task 数ではありません。デフォルトモデルでは TaskCreate を利用できません（rules/task-tracking-availability.md を参照）。task 数を分母にすると、ツールのない環境ではゼロになってしまいます。session で Task ツールが使える場合は、このリストを TaskCreate に別途反映しても構いません。

---

Step 2.5：実行レポートを生成する

<plan-dir>/.plan-state/<slug>.state.json（<slug> は plan ファイル名から .md を除いたもの）が存在するか確認します。all_done 後に runner が自動生成した <plan-dir>/.plan-state/<slug>.report.md があれば、概要を把握するために先に読んでも構いません。ただし、plan に実際に埋め込む内容は、以下の report を再実行した出力を必ず使用します。all_done 後に complete／skip（たとえば後から概要を補う場合）が実行されるたびにそのファイルは書き換えられますが、その他の state を書き込む操作（reset など）では書き換えられないため、再生成するのが最も確実です。

存在する場合：次を実行します

python3 ~/Documents/agent-skills/scripts/plan_runner.py report <plan>

stdout をそのまま plan の ## 執行摘要 セクションに貼り付けます（セクションがすでにある場合は全体を置き換え、重複して追記しないでください）。位置は ## 驗證結果 の前です。--output を追加して別ファイルに書き出してはいけません。別ファイルは Step 4 の mv と一緒に移動する必要があり、移動し忘れると孤立します。KB ingest でも別ファイルと plan は関連付けられず、後から 2 つのファイルが別々に更新されてしまいます。

存在しない場合：## 執行摘要 セクションに「（本 plan 未經 /plan-run 推進，無執行紀錄）」と 1 行記載し、次のステップに進みます。

移動前に行う理由：state は .plan-state/ 隠しディレクトリにあり、Step 4 の mv では .md だけが移動されます。アーカイブ後は plan と state が別々になるため、実行記録を保存するには、先に plan 自体へ埋め込む必要があります。レポート形式は parse_plan に影響しません（冒頭は常に ### 執行摘要 で Phase という文字列を含まず、各 phase の見出しは #### を使用し、- [ ] リストは使いません（集計セクションと「未完成與例外」のリスト項目は、すべて - **<step>** で始まります）。概要の各行は > 引用で始まり、それ以外の行も空白または # で始まらず、全体が ## 執行摘要 の下に置かれます）。そのため、アーカイブ後の plan を再度 init しても、step や phase が追加されることはありません。

Step 3 の検証表では、レポート内の「未完成與例外」にある failed／skipped のリストをそのまま引用でき、項目を改めて一つずつ照合する必要はありません。

---

Step 3：検証結果を追記する

plan ファイルの先頭（--- の frontmatter 直後）に以下を追加します：

**狀態：✅ 完成（YYYY-MM-DD）**

次に ## 驗證結果 セクションを追記または更新し、Step 2 で作成したリストと項目ごとに照合します：

#	Phase/Step	期待される結果	実際の結果	状態
1	Phase 1: ...	...	...	PASS/FAIL

FAIL の項目には説明を必ず添えます（許容可能な差異か、未解決の問題かを記載します）。

plan に ## Industry & Standards Reference がある場合は、その各項目が実施されているかを照合します（APPLIED／PARTIAL／NOT_APPLIED。後者 2 つには理由として、環境上の制約、決定の変更、または未対応を記載します）。

完了率 = PASS の step 数 / step の合計数：

• < 100%：警告 — 未完了の step があります。既知の許容可能な差異かどうか確認してください
• < 80%：アーカイブを阻止 — ユーザーに伝え、アーカイブを続行するか確認してください

テストの合格数、差異、補足説明など、その他の内容はこのセクションに残します。

---

Step 4：ファイルを移動する

mkdir -p plans/completed
mv plans/active/<filename>.md plans/completed/<filename>.md

移動の成功を確認したら、✅ アーカイブしました：plans/completed/<filename>.md と出力します。最終返信には、埋め込んだ実行概要の要約版を必ず含めてください：レポートのパスを独立した行に記載し（例：レポート：plans/completed/<filename>.md（## 執行摘要 セクション）、ユーザーが直接ファイルを開いてレビューできるようにします）、Progress の進捗行、#### 彙整 にある 3 つのリスト（plan からの逸脱／副作用／延期された保留タスク）の全文、各 phase の step 状態表（step ごとの概要引用は省略可）、Step 2.5 の「未完成與例外」セクション全文を含めます。概要をアーカイブ後の .md に埋め込むだけでは納品になりません。ユーザーが今回の返信内で確認できるようにしてください。Step 2.5 で「実行記録なし」と判定された plan については、ここで「（本 plan 未經 /plan-run 推進，無執行紀錄）」とそのまま返し、概要の内容を捏造する必要はありません。

---

自動化（任意）

ExitPlanMode のたびに plan を自動で plans/active/ に保存する方法については、docs/hooks-setup.md を参照してください。

---

ディレクトリ規則

plans/
├── active/       # 進行中（Hook 自動存入 / /plan 手動建立）
├── completed/    # 已實作完成（/plan-archive 歸檔）
└── archived/     # 長期封存（不再參考的舊 plan）