aif-archive

Archive — 完了した計画とロードマップのスナップショットを移動する

完了した単一ファイルの計画と ultra バンドルディレクトリを paths.plans/ から paths.archive/plans/ に移動し、 必要に応じて、完了したマイルストーンを ROADMAP.md から日付付きスナップショットとして paths.archive/roadmap/ に移動します。

ワークフロー

ステップ 0：設定を読み込む

.ai-factory/config.yaml が存在する場合は読み込み、次の値を解決します。

• paths.plans（デフォルト：.ai-factory/plans/）
• paths.archive（デフォルト：.ai-factory/archive/）
• paths.plan（デフォルト：.ai-factory/PLAN.md）
• paths.fix_plan（デフォルト：.ai-factory/FIX_PLAN.md）
• paths.roadmap（デフォルト：.ai-factory/ROADMAP.md）
• workflow.plan_id_format（デフォルト：slug）— 有効な値：slug と sequential。timestamp と uuid は予約済みで、slug と同様に動作します。 不明な値は slug として扱います。
• ユーザー向けプロンプトの language.ui

設定ファイルが存在しない場合は、上記のデフォルト値を使用します。

.ai-factory/skill-context/aif-archive/SKILL.md が存在する場合は読み込みます。 プロジェクト固有の上書き指示は一般的な指示より優先されます。

ステップ 1：引数を解析する

引数からモードを抽出します。

(no args)        → interactive mode: scan, show completable plans, ask which to archive
list             → show archive contents, then STOP
--roadmap        → trim closed milestones from ROADMAP.md into a snapshot
--all            → archive ALL completed plans (ask confirmation first)
<plan-name>      → archive a specific plan by filename or partial stem match

解析ルール：

• list と --roadmap は、<plan-name> および --all と同時に指定できません。
• 複数の競合するモードが指定された場合は、エラーを出力して停止します。
• <plan-name> には次のいずれかを指定できます。
  • 完全なファイル名：0005_feature-auth.md
  • ultra ディレクトリ／エントリーポイント：0005_feature-auth または 0005_feature-auth/index.md
  • 拡張子なしのファイル名：0005_feature-auth
  • 部分一致：feature-auth（一致する計画が 1 つだけである必要があります）

ステップ 2：モードを実行する

---

モード：対話型（引数なし）

1. Glob を使用して paths.plans/ をスキャンし、ルート直下の *.md ファイルと、直接の子ディレクトリにある */index.md を候補として探します。解決済みの paths.plan と paths.fix_plan は除外し、エントリーポイントに `` が宣言されているディレクトリのみを数えます。フェーズファイルや無関係なディレクトリは計画として扱いません。
2. 各成果物について、エントリーポイントの ## Tasks セクションを読み込みます。
3. 完了状況を判定します。すべてのタスクのチェックボックスが - [x] の場合、その計画は完了です。- [ ] が 1 つでもある計画は未完了です。
4. 完了した計画が見つからない場合：

   No completed plans found in <paths.plans/>.
   

   → 停止します。
5. 完了した計画を表示します。

   Completed plans ready to archive:
   
     1. 0001_feature-alpha.md (completed 2026-05-20)
     2. 0003_feature-gamma.md (completed 2026-05-24)
   
   Incomplete plans (skipped):
     - 0005_feature-delta.md (3/7 tasks done)
   

6. アーカイブする計画を尋ねます。

   AskUserQuestion: Which plans to archive?
   
   Options:
   1. All completed plans listed above
   2. Select specific plans (enter numbers)
   3. Cancel
   

7. 選択された計画に対してアーカイブ操作を実行します（アーカイブ操作を参照）。

---

モード：list

1. <paths.archive>/plans/ が存在するか確認します。
2. 存在しない場合：Archive is empty. No plans have been archived yet. → 停止します。
3. ルート直下の <paths.archive>/plans/*.md ファイルと、<paths.archive>/plans/*/index.md にある、` `` がちょうど 1 つ含まれるエントリーポイントを Glob で検索します。
4. アーカイブ済みの各成果物について、YAML フロントマター、または ultra マーカーの直後にある ``（index.md）から日付を抽出します。
5. 次を表示します。

   Archived plans (<paths.archive>/plans/):
   
     1. 0001_feature-alpha.md  (archived: 2026-05-20)
     2. 0003_feature-gamma.md  (archived: 2026-05-24)
   
   Total: 2 archived plans
   

6. <paths.archive>/roadmap/ にスナップショットがあるか確認し、存在する場合は一覧表示します。

   Roadmap snapshots (<paths.archive>/roadmap/):
   
     1. 2026-05-20_roadmap-snapshot.md (3 milestones)
   

7. 停止します。

---

モード：<plan-name>

1. <plan-name> を paths.plans/ 内の 1 つの成果物に解決します。
   • まず、ルート直下のファイル名、ultra ディレクトリ、または */index.md と完全一致するか確認します。
   • 次に、.md 拡張子を付けて確認します。
   • その後、ルート直下のファイル名および ultra ディレクトリ名との部分一致を試します。
2. 一致するものがない場合：候補を提示し、Plan not found: <plan-name> を表示して停止します。
3. 複数一致する場合：一覧表示し、ユーザーにさらに具体的に指定するよう求めて停止します。
4. ディレクトリが一致した場合は、エントリーポイントを読み込み、 `` があることを確認します。なければ、アーカイブ可能な AI Factory の計画ではありません。
5. 一致したエントリーポイントを読み込み、完了状況を確認します。
6. 未完了の場合：

   Plan <filename> is not completed (5/8 tasks done).
   Only completed plans can be archived.
   

   → 停止します。
7. アーカイブ操作を実行します（アーカイブ操作を参照）。

---

モード：--all

1. 完了した計画を探すため、paths.plans/ をスキャンします（対話型モードと同じロジック）。
2. 完了した計画が見つからない場合は、その旨を伝えて停止します。
3. 一覧を表示し、確認を求めます。

   AskUserQuestion: Archive ALL completed plans?
   
     1. 0001_feature-alpha.md
     2. 0003_feature-gamma.md
   
   Options:
   1. Yes, archive all 2 plans
   2. Cancel
   

4. 確認されたすべての計画に対してアーカイブ操作を実行します。

---

モード: --roadmap

1. 解決された paths.roadmap ファイルを読み取ります。
2. 存在しない場合: No ROADMAP.md found at <path>. → 停止します。
3. - [x] チェックボックスが付いたマイルストーン（完了したマイルストーン）を探します。
4. 完了したマイルストーンがない場合: No closed milestones to archive. → 停止します。
5. 表示して確認を求めます:

   Closed milestones found in ROADMAP.md:
   
     - [x] MVP Launch — core features shipped
     - [x] Beta Testing — user feedback round
   
   AskUserQuestion: Trim these milestones from ROADMAP.md into a snapshot?
   
   Options:
   1. Yes, create snapshot and trim
   2. Cancel
   

6. スナップショットを作成します:
   • mkdir -p <paths.archive>/roadmap/
   • スナップショットのファイル名を決定します: YYYY-MM-DD_roadmap-snapshot.md
   • 衝突チェック。 書き込む前に、宛先がまだ存在しないことを確認します:

     Read <paths.archive>/roadmap/YYYY-MM-DD_roadmap-snapshot.md
     

     ファイルが存在する場合は、カウンターサフィックスを付加して衝突しない名前を生成します: YYYY-MM-DD_roadmap-snapshot-2.md、YYYY-MM-DD_roadmap-snapshot-3.md など。 空いている名前が見つかるまで、各候補を確認します。
   • 解決されたスナップショットパスを次の内容で書き込みます:

     # Roadmap Snapshot — YYYY-MM-DD
     
     Archived from: <paths.roadmap>
     
     ## Archived Milestones
     
     - [x] MVP Launch — core features shipped
     - [x] Beta Testing — user feedback round
     

7. paths.roadmap を編集します: ## Milestones セクションからアーカイブされた - [x] 行を削除します。## Completed テーブルが存在する場合はそのままにします。 ステップ 6 のスナップショット書き込みが成功しない限り、paths.roadmap を編集しないでください。
8. ログ出力: INFO [aif-archive] roadmap snapshot: <resolved-path> (<N> milestones archived)

---

アーカイブ操作（プラン）

アーカイブするプラン成果物ごとに、次の手順を実行します。

1. mkdir -p <paths.archive>/plans/

2. 競合チェック。 移動する前に、移動先がすでに存在していないことを確認します。

   Read <paths.archive>/plans/<original-name>          # full plan
   Read <paths.archive>/plans/<original-name>/index.md # ultra bundle
   

   ファイルが存在する場合：

   • 単一のプラン（対話形式または<plan-name>）：エラーで停止します。

     ERROR [aif-archive] destination already exists: <paths.archive>/plans/<filename>
     A previously archived plan has the same filename. This can happen when
     sequential numbering reuses a freed number after archiving.
     To resolve: rename the existing archive file, or delete it if it is no
     longer needed.
     

   • 一括処理（--all）：このプランを警告とともにスキップし、次のプランに進みます。

     WARN [aif-archive] skipped: <filename> — destination already exists
     

   どちらの場合も上書きしてはいけません。

3. 移動する前に、ultra バンドルを検証します。 index.md を読み込み、次の条件を満たすことを確認します。

   • , または任意の1行目のの直後に、ちょうど1つだけ存在すること
   • 空でない ## Phase Index があること
   • リンク先のフェーズパスがすべてバンドルの直下にあり、実在すること

   不正なバンドルは安全にアーカイブできません。単一のプランの場合は停止し、--allモードの場合は WARN [aif-archive] skipped malformed ultra bundle: <filename> を出力して続行します。

4. ソース成果物全体を、まずアーカイブパスに移動します。

   mv <paths.plans>/<name> <paths.archive>/plans/<name>
   

   ultra の場合、<name> はディレクトリ全体を指すため、リンク先のフェーズファイルもすべて一緒に移動します。これにより、プランはアクティブな検索対象からアトミックに取り除かれます。

5. Edit を使って、移動後のエントリーポイントにアーカイブのメタデータを追加します（ultra では index.md、それ以外では移動したプランファイル）。

   ultra の場合、正規のヘッダーを保持し、このコメントを `` の直後に挿入します。

   YAML を先頭に追加したり、ultra マーカーを移動したりしてはいけません。マーカーは、任意の1行目の Handoff 注釈がある場合はその直後、そうでなければ1行目に残す必要があります。

   フルプランに YAML フロントマター（先頭の --- マーカーで囲まれた部分）がすでにある場合：

   • Edit を使って、既存のフロントマターブロック内に archived: YYYY-MM-DD フィールドを追加します。

   フルプランに YAML フロントマターがない場合：

   • Edit を使って、次の最小限のフロントマターブロックを1行目より前に追加します。

     ---
     archived: YYYY-MM-DD
     ---
     

   連番の NNNN_ プレフィックスも含め、元のファイル名またはディレクトリ名はそのまま保持します。

6. ログ：INFO [aif-archive] archived: <filename> -> <paths.archive>/plans/<filename>

7. すべてのプランの処理後、次のサマリーを表示します。

   ## Archive Complete
   
   Archived N plan(s) to <paths.archive>/plans/:
     - 0001_feature-alpha.md
     - 0003_feature-gamma.md
   
   Skipped: K (destination already exists)
     - 0002_feature-beta.md
   
   Plans directory: <paths.plans/> (M plans remaining)
   

   K が 0 の場合、「Skipped」セクションは省略します。

完了判定アルゴリズム

プランは、次の条件を満たす場合に完了と判定されます。

1. プランのエントリーポイントに ## Tasks セクションがある（見出しの大文字・小文字は区別しません）。
2. Tasks セクションおよびそのサブセクション内で - [x] または - [ ] のパターンに一致するすべての行がチェック済みである。すべてのチェックボックスが - [x] である必要があります。
3. Tasks セクションにチェックボックスが1つもない場合、プランは未完了と判定されます（空のプランはアーカイブできません）。

例外：

• ## Tasks の外にあるチェックボックス（例：## Settings や ## Commit Plan 内）は、完了判定の対象になりません。
• 入れ子になったチェックボックス（インデントされた - [x]）も対象になります。
• エントリーポイントに ## Tasks がないプランはアーカイブできません。WARN [aif-archive] <name> has no ## Tasks section; skipping を出力します。

完了日の推定

対話モードで「completed」の日付を表示する場合：

1. YAML フロントマターで completed フィールドを確認し、存在する場合はその値を使用します。
2. なければ、Git で git log -1 --format=%ai -- <plan-file> を実行して、最終変更日を取得します。
3. それも取得できない場合は、ファイルシステムのエントリーポイントの更新日時を使用します。

重要なルール

1. 未完了の計画はアーカイブしないでください — すべてのタスクを - [x] にする必要があります
2. --all および --roadmap の操作を行う前に、必ず確認を求めてください
3. 元のファイル名／ディレクトリ名を保持してください — 連番の NNNN_ プレフィックスも含みます
4. アーカイブメタデータを追加してください — 完全な計画には YAML フロントマターを、バンドルには ultra マーカーの後に安定した `` コメントを追加してください
5. fast plans（paths.plan）または fix plans（paths.fix_plan）は変更しないでください — これらは /aif-implement と /aif-fix が管理する単一ファイルの成果物です
6. 連番の採番時にアーカイブ済みの計画を数えないでください — アーカイブ済みの計画は paths.plans/ ではなく paths.archive/plans/ にあるため、/aif-plan の連番スキャンには含まれません

成果物の管理範囲

• 管理対象: paths.archive/plans/*.md、アーカイブ済みの ultra バンドルディレクトリ、paths.archive/roadmap/*.md
• 読み取り対象: ルートの paths.plans/*.md、直下の ultra */index.md とリンクされたフェーズ、paths.roadmap
• 変更対象: paths.roadmap（--roadmap を指定し、確認を得た後に限る）
• 変更しないもの: paths.plan、paths.fix_plan、paths.description、 paths.architecture、paths.rules_file