# GSD-2 から移行する方法

**目標:** 古い GSD-2 プロジェクト（`.gsd/` ディレクトリレイアウト）を MSD Core（`.planning/` レイアウト）に移行し、リポジトリ内に存在する ADR、PRD、仕様書などを新しい計画構造に取り込む。

**前提条件:** MSD Core がインストール済みであること。GSD-2 プロジェクトディレクトリがディスク上にアクセス可能な状態であること。

---

## 何が移行されるかを理解する

GSD-2 は計画ルートとして `.gsd/` ディレクトリを使用していました。MSD Core は `.planning/` を使用します。移行はこれを逆転させます。`.gsd/` の成果物を読み込み、すべての MSD Core コマンドが期待する標準的な `.planning/` 構造に書き込みます。

| GSD-2 に存在するもの | `/msd-import --from-gsd2` が生成するもの |
|----------------------|-----------------------------------------|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
| `.gsd/STATE.md` | `.planning/STATE.md` |
| `.gsd/phases/` ディレクトリ | `.planning/phases/` ディレクトリ |
| フェーズの `PLAN.md` ファイル | MSD Core の `{NN}-{MM}-PLAN.md` ファイル（名前変更を強制） |

ファイルが書き込まれる前に競合検出が実行されます。対象ディレクトリにすでに `PROJECT.md` があり、インポートするコンテンツと矛盾する場合、移行は BLOCKER ゲートで停止し、解決すべき競合を一覧表示します。

---

## 移行を実行する

### 現在のディレクトリを移行する

```bash
/msd-import --from-gsd2
```

MSD は現在の作業ディレクトリの `.gsd/` を読み込み、移行した成果物を `.planning/` に書き込みます。

### 別のパスから移行する

```bash
/msd-import --from-gsd2 --path ~/projects/old-project
```

GSD-2 プロジェクトが現在の作業ディレクトリでない場合は `--path` を使用します。

---

## 競合を解決する

競合検出がブロッカーを見つけた場合（例：GSD-2 の技術スタック宣言が既存の `.planning/PROJECT.md` と矛盾する）、競合レポートを表示してファイルを書き込まずに停止します。

レポートを読み、矛盾を解消（ソース文書または既存の計画成果物を編集）してから、`/msd-import --from-gsd2` を再実行します。移行はクリーンに通過するまで安全に再実行できます。

---

## 外部プランファイルをインポートする

完全な GSD-2 プロジェクトではなく、スタンドアロンのプランドキュメント（チームの計画ドキュメント、Markdown 仕様、エクスポートされたタスクリスト）がある場合は、代わりに `--from` を使用します。

```bash
/msd-import --from /tmp/team-plan.md
```

MSD は同じ競合検出パスを実行し、コンテンツを MSD Core の `PLAN.md` 形式に変換し、プランチェッカーで結果を検証します。検証後、対象ファイル名と次のステップが表示されます。

---

## 既存のドキュメントを取り込む

リポジトリに ADR（アーキテクチャ決定記録）、PRD、仕様ドキュメントがすでに存在する場合は、移行後に `/msd-ingest-docs` を使って `.planning/` 構造に統合します。

### リポジトリ全体をスキャンする（モードを自動検出）

```bash
/msd-ingest-docs
```

`.planning/` がすでに存在する場合（例：今実行した移行から）、MSD はデフォルトでマージモードになります。既存のものを上書きするのではなく、インポートしたドキュメントを既存のものと並べて統合します。

### 特定のディレクトリにスコープを絞る

```bash
/msd-ingest-docs docs/
/msd-ingest-docs docs/adr/
```

### 明示的な優先度マニフェストを使用する

ドキュメントのタイプが混在している場合や、競合時にどのドキュメントが優先されるかを制御したい場合：

```bash
/msd-ingest-docs --manifest ingest.yaml
```

マニフェストはドキュメントごとに `{path, type, precedence?}` を列挙する YAML ファイルです。期待される形式については、[コマンドリファレンス](../COMMANDS.md)の `--manifest` フラグの説明を参照してください。

### 特定のモードを強制する

```bash
/msd-ingest-docs --mode merge     # 既存の .planning/ にマージする
/msd-ingest-docs --mode new       # 最初から構築する（上書き）
```

**出力:** `/msd-ingest-docs` は常に 3 つのバケット（自動解決済み、競合バリアント、未解決ブロッカー）を含む `INGEST-CONFLICTS.md` を生成します。すべてのインポート実行後にこのファイルを確認してください。ハードストップは LOCKED 対 LOCKED の ADR 矛盾の場合のみ発生します。それ以外はすべて確認のために表示され、サイレントに破棄されることはありません。

---

## 移行したプロジェクトを検証する

移行とドキュメントの取り込みが完了したら、プロジェクト状態の一貫性を確認します。

```bash
/msd-health
/msd-health --repair
```

`/msd-health` は `.planning/` ディレクトリの整合性を確認し、ドリフトを報告します。`--repair` は回復可能な問題を自動修正します。

次に、MSD Core がプロジェクト状態を読み込めることを確認します。

```bash
/msd-progress
```

プロジェクトが正常に移行されていれば、現在のフェーズステータスと推奨される次のステップが表示されます。ここから標準的な MSD Core ワークフローが適用されます。

---

## 条件分岐：何が移行されて何がされないか

| 状況 | 対応 |
|-----------|-----------|
| `.gsd/` が現在のディレクトリにある | `/msd-import --from-gsd2` を実行する（`--path` 不要） |
| `.gsd/` が別のディレクトリにある | `--path ~/projects/old-project` を使用する |
| 完全な GSD-2 プロジェクトではなくスタンドアロンのプランドキュメントがある | `/msd-import --from /path/to/plan.md` を使用する |
| `docs/adr/` に ADR がある | 移行後に `/msd-ingest-docs docs/adr/` を実行する |
| ADR、PRD、仕様の混在がある | リポジトリルートで `/msd-ingest-docs` を実行する（自動分類） |
| 競合検出がブロッカーを報告する | 一覧表示された矛盾を解消してから再実行する；すべてのブロッカーがクリアになるまでファイルは書き込まれない |
| 移行が成功したか不明 | `/msd-health` と `/msd-progress` を実行して確認する |
| INGEST-CONFLICTS.md に未解決のブロッカーが残っている | 対象ドキュメントが計画に取り込まれる前に手動での解決が必要 |

---

## Related

- [初めてのプロジェクト](../tutorials/your-first-project.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)