機能仕様書: 4層リリースフロー（feature → develop → release/* → main）

## Spec

# 機能仕様書: 4層リリースフロー（feature → develop → release/* → main）

**機能ID**: `SPEC-1ac96646`
**作成日**: 2025-11-07
**最終更新**: 2025-11-09
**ステータス**: 実装完了
**入力**: ユーザー説明: "4層リリースフロー（feature → develop → release/* → main）の実装"

## ユーザーシナリオ＆テスト *(必須)*

### ユーザーストーリー1 - developブランチへのPR自動マージ (優先度: P1)

開発者として、featureブランチでの作業が完了したら、developブランチへのPRを作成し、CI/CDチェックが成功したら自動的にマージされることで、手動マージの手間を削減し、開発速度を向上させたい。

**この優先度の理由**: これは3層フローの基盤となる機能です。developブランチが正しく機能しなければ、後続のリリースフローが成立しません。最も基本的で重要な機能のため、P1としています。

**独立テスト**: finish-feature.shスクリプトを実行してdevelopへのPRを作成し、CI/CDチェック成功後に自動マージされることを確認することで完全にテストできます。この機能だけで、開発者はfeatureブランチからdevelopへスムーズに統合できる価値を提供します。

**受け入れシナリオ**:

1. **前提** featureブランチで作業が完了、**実行** finish-feature.shを実行、**結果** developをベースとしたPRが作成される
2. **前提** developへのPRが作成済み、**実行** CI/CDチェックがすべて成功、**結果** PRが自動的にdevelopにマージされる
3. **前提** developへのPRが作成済み、**実行** CI/CDチェックが失敗、**結果** PRは自動マージされず、コメントで失敗を通知される

---

### ユーザーストーリー2 - /releaseコマンドによる手動リリース (優先度: P2)

プロジェクトマネージャー/リリース担当者として、developブランチの変更を蓄積した後、意図的なタイミングでリリースを開始したい。/releaseコマンドを実行すると、release/vX.Y.Zブランチが作成され、そこでsemantic-releaseが実行されてバージョン決定とCHANGELOG生成が行われる。その後、release/*ブランチからmainへ自動マージされることで、リリースプロセスを自動化したい。

**この優先度の理由**: リリース頻度の削減という主要な目標を達成するための核心機能です。developブランチへの統合ができた後、次に重要なのは、意図的なタイミングでのリリース実行です。

**独立テスト**: /releaseコマンドを実行し、release/vX.Y.Zブランチが作成され、semantic-releaseが実行され、mainへ自動マージされることを確認することでテストできます。この機能により、リリース担当者は適切なタイミングでリリースをコントロールできる価値を提供します。

**受け入れシナリオ**:

1. **前提** developブランチに複数のfeatureがマージ済み、**実行** /releaseコマンドを実行、**結果** release/vX.Y.Zブランチが作成され、developからのPRが作成される
2. **前提** release/* PR作成済み、**実行** CI/CDチェック成功、**結果** semantic-releaseが実行され、バージョン決定とCHANGELOG生成が完了する
3. **前提** semantic-release完了、**実行** release.ymlワークフロー実行、**結果** release/*ブランチがmainに自動マージされる
4. **前提** mainマージ完了、**実行** バックマージワークフロー実行、**結果** mainの変更がdevelopにバックマージされる

---

### ユーザーストーリー3 - 自動リリース成果物配信 (優先度: P3)

エンドユーザー/パッケージ利用者として、mainブランチへのマージ後、自動的にMCPサーバーがnpmjs.comに公開され、LSPサーバーが全プラットフォームでビルドされ、GitHub Releaseが作成されることで、最新バージョンをすぐに利用できるようにしたい。

**この優先度の理由**: リリースフローの自動化により、手動作業を削減し、リリースの一貫性を保証します。mainへのマージが正しく動作した後に必要となる機能のため、P3としています。

**独立テスト**: mainブランチへのマージを実行し、semantic-releaseが自動的に実行され、npmjs.comへのpublish、LSPサーバーのビルド、GitHub Releaseの作成がすべて完了することを確認することでテストできます。この機能により、エンドユーザーは最新バージョンを即座に利用できる価値を提供します。

**受け入れシナリオ**:

1. **前提** release/*→ main マージ済み、**実行** semantic-releaseが自動実行（release/*ブランチ上）、**結果** package.json、Unity Package、CHANGELOG.mdが更新され、タグが作成される
2. **前提** semantic-release完了、**実行** GitHub Releaseが作成、**結果** MCPサーバーがnpmjs.comに自動publishされる
3. **前提** GitHub Release作成済み、**実行** LSPサーバービルドジョブ実行、**結果** 全プラットフォーム（linux-x64, osx-x64, osx-arm64, win-x64）のバイナリがGitHub Releaseに添付される

---

### ユーザーストーリー4 - 既存PR移行 (優先度: P4)

開発者として、現在mainベースで作成されている16個のfeature PRを、新しいdevelopブランチベースに一括変更することで、既存の作業を中断せずに新しいフローに移行したい。

**この優先度の理由**: 既存作業の移行は重要ですが、新しいフローの基盤が整ってから実施すべきです。P1〜P3の機能が動作確認できた後に実施するため、P4としています。

**独立テスト**: PR移行スクリプトを実行し、16個のPRのベースブランチがすべてdevelopに変更され、変更後のPRが正常に動作することを確認することでテストできます。この機能により、開発者は既存作業を失わずに新フローに移行できる価値を提供します。

**受け入れシナリオ**:

1. **前提** mainベースのfeature PRが16個存在、**実行** PR移行スクリプトを実行、**結果** すべてのPRのベースブランチがdevelopに変更される
2. **前提** PRのベースブランチ変更完了、**実行** CI/CDチェック再実行、**結果** すべてのPRでチェックが正常に動作する
3. **前提** 移行後のPRが1つ成功、**実行** auto-mergeワークフロー実行、**結果** developに正常にマージされる

---

### ユーザーストーリー5 - OpenUPM自動配信 (優先度: P5)

Unity開発者として、mainブランチへのリリース時にOpenUPMパッケージレジストリに自動配信されることで、Unity Package Manager経由で簡単にインストールできるようにしたい。また、OpenUPMのパッケージページで十分な情報（README、homepage）が表示されることで、パッケージの用途と使い方を理解したい。

**この優先度の理由**: OpenUPM配信はエンドユーザー体験を向上させますが、npm publishとLSPビルドが完了した後に追加する付加価値機能のため、P5としています。

**独立テスト**: mainブランチへのマージ後、OpenUPM側のビルドパイプラインが自動的にトリガーされ、パッケージがOpenUPMレジストリに公開され、パッケージページにREADMEとhomepageが正しく表示されることを確認することでテストできます。この機能により、Unity開発者はUPM経由で簡単にインストールできる価値を提供します。

**受け入れシナリオ**:

1. **前提** mainブランチにリリースがマージ済み、**実行** OpenUPM側がGitHubタグを検出、**結果** OpenUPMビルドパイプラインが自動実行される
2. **前提** OpenUPMビルド完了、**実行** OpenUPMパッケージページを確認、**結果** 最新バージョンが表示され、README内容とhomepageリンクが正しく表示される
3. **前提** OpenUPM配信完了、**実行** Unity EditorでUPM経由でインストール、**結果** パッケージが正常にインストールされる

---

### エッジケース

- developブランチがまだ存在しない場合、どのように作成するか？
  - **対応**: mainブランチの最新コミットからdevelopブランチを作成し、GitHub上でデフォルトブランチをdevelopに変更する

- /releaseコマンド実行時にdevelopとmainに差分がない場合、何が起こるか？
  - **対応**: リリースノートプレビューで「変更なし」を表示し、PR作成をスキップする

- semantic-release実行中にエラーが発生した場合、どのように処理するか？
  - **対応**: リリースジョブを失敗させ、GitHub上でエラー通知を表示。手動介入が必要

- LSPサーバービルドが一部のプラットフォームで失敗した場合、どうするか？
  - **対応**: 成功したプラットフォームのバイナリのみGitHub Releaseに添付し、失敗したプラットフォームはエラーログを残す

- PR移行スクリプト実行中にネットワークエラーが発生した場合、どうするか？
  - **対応**: 移行済みPRをログに記録し、リトライ時にスキップする。べき等性を保証

## 要件 *(必須)*

### 機能要件

- **FR-001**: システムは、finish-feature.shスクリプト実行時にdevelopブランチをベースとしたPRを作成する必要がある
- **FR-002**: システムは、developへのPRに対してCI/CDチェック成功時に自動マージを実行する必要がある
- **FR-003**: システムは、mainへのPRに対して自動マージを実行してはならない（手動承認必須）
- **FR-004**: システムは、/releaseコマンド実行時にrelease/vX.Y.Zブランチを作成し、developからのPRを作成する必要がある
- **FR-005**: システムは、release/*ブランチ上でsemantic-releaseを自動実行し、package.json、Unity Package、CHANGELOG.mdを更新し、タグを作成する必要がある
- **FR-006**: システムは、semantic-release完了後にrelease/*ブランチをmainに自動マージする必要がある
- **FR-007**: システムは、mainマージ後にdevelopへバックマージする必要がある
- **FR-008**: システムは、GitHub Release作成時にMCPサーバーをnpmjs.comに自動publishする必要がある
- **FR-009**: システムは、LSPサーバーを全プラットフォーム（linux-x64, osx-x64, osx-arm64, win-x64）でビルドし、GitHub Releaseに添付する必要がある
- **FR-010**: システムは、PR移行スクリプト実行時に既存16個のfeature PRのベースブランチをdevelopに一括変更する必要がある
- **FR-011**: システムは、PR移行後もCI/CDチェックが正常に動作することを保証する必要がある
- **FR-012**: GitHub上のデフォルトブランチはdevelopである必要がある
- **FR-013**: CLAUDE.md、README.md、quickstart.mdは4層ブランチフロー（feature → develop → release/* → main）を反映した内容に更新される必要がある
- **FR-014**: システムは、Unity Packageのpackage.jsonに`homepage`フィールドを含める必要がある（OpenUPMパッケージページでの情報表示のため）
- **FR-015**: システムは、Unity PackageルートにREADME.mdを配置する必要がある（OpenUPMパッケージページでのREADME埋め込みのため）

### 主要エンティティ

- **ブランチ**: feature, develop, release/*, mainの4層構造。featureはdevelopから派生、release/*はdevelopから作成され、mainは安定版リリース専用
- **プルリクエスト**: feature → develop（自動マージ）、develop → release/*（/releaseコマンドで作成）、release/* → main（自動マージ）、main → develop（バックマージ）の4種類
- **リリース成果物**: MCPサーバー（npm）、LSPサーバー（全プラットフォームバイナリ）、Unity Package、CHANGELOG、タグ、OpenUPMパッケージ
- **CI/CDワークフロー**: auto-merge（developのみ）、release（mainのみ）、unity-cli-publish（GitHub Release作成時）
- **パッケージメタデータ**: package.json（homepage、version）、README.md（パッケージルート配置）

---

## スコープ外 *(オプション)*

以下の機能は本仕様のスコープ外とし、将来のバージョンで対応予定:

- ホットフィックスブランチ（hotfix → main → develop）
- ロールバック機能（リリース後に問題が発覚した場合の自動ロールバック）
- マルチバージョンサポート（複数のメジャーバージョンの並行保守）

---

## 技術制約 *(該当する場合)*

- GitHub Actionsが利用可能である必要がある
- gh CLI（GitHub CLI）がインストールされている必要がある
- npm publishにはnpmjs.comのアクセストークンが必要
- LSPサーバービルドには.NET SDKが必要
- semantic-releaseはConventional Commits規約に依存する

---

## 前提条件 *(該当する場合)*

この機能は以下を前提とします:

- 既存のGitHub Actionsワークフロー（auto-merge.yml、release.yml、unity-cli-publish.yml）が動作している
- semantic-release設定（.releaserc.json）が存在する
- finish-feature.shスクリプトが存在する
- Conventional Commits規約に従ったコミットメッセージが使用されている

---

## 依存関係 *(該当する場合)*

この機能は以下に依存します:

- **GitHub Actions**: CI/CD実行基盤
- **semantic-release**: 自動バージョニング＆リリースノート生成
- **gh CLI**: PR操作の自動化
- **npm**: MCPサーバーの配信
- **.NET SDK**: LSPサーバーのビルド
- **Unity Recorder**: 動画キャプチャ（既存依存関係）

---

## 成功基準 *(必須)*

以下の成功基準を満たす必要があります:

1. **リリース頻度の削減**: featureマージごとのリリースから、意図的なタイミングでのリリース（週1回〜月1回程度）に削減される
2. **自動マージの成功率**: developへのPRの95%以上がCI/CDチェック成功後に自動マージされる
3. **リリース成果物の完全性**: mainマージ後、100%のケースでMCPサーバー（npm）、LSPサーバー（全プラットフォーム）、GitHub Releaseが正常に作成される
4. **PR移行の成功率**: 既存16個のPRの100%がdevelopベースに移行され、CI/CDチェックが正常に動作する
5. **リリース所要時間**: /releaseコマンド実行からGitHub Release作成まで、平均30分以内に完了する
6. **ドキュメント整合性**: CLAUDE.md、README.md、quickstart.mdが3層フローを正確に反映し、開発者が迷わずフローを理解できる
7. **OpenUPM配信の信頼性**: mainマージ後、OpenUPMビルドが自動的にトリガーされ、パッケージページでREADMEとhomepageが正しく表示される（100%のケース）

**成功基準の測定方法**:

1. **リリース頻度**: GitHub Releaseの作成間隔を計測（平均7日以上）
2. **自動マージ成功率**: auto-mergeワークフロー成功回数 ÷ 実行回数 × 100（95%以上）
3. **リリース成果物**: release.ymlとunity-cli-publish.ymlのジョブ成功率（100%）
4. **PR移行成功率**: 移行後のPRのCI/CDチェック成功数 ÷ 16 × 100（100%）
5. **リリース所要時間**: /release実行タイムスタンプ 〜 GitHub Release作成タイムスタンプの差分（30分以内）
6. **ドキュメント整合性**: レビューチェックリストで確認（100%一致）
7. **OpenUPM配信**: OpenUPMパッケージページでREADMEとhomepageが表示されることを手動確認（各リリースで確認）

---

## ⚡ クイックガイドライン

- ✅ ユーザーが「何を」必要とし「なぜ」必要なのかに焦点を当てる
- ❌ 「どのように」実装するかを避ける (技術スタック、API、コード構造なし)
- 👥 ビジネス関係者向けに記述 (開発者向けではない)

## Plan

# 実装計画: 3層リリースフロー（feature → develop → main）

**機能ID**: `SPEC-1ac96646` | **日付**: 2025-11-07 | **仕様**: [spec.md](./spec.md)
**入力**: `/specs/SPEC-1ac96646/spec.md`の機能仕様

## 実行フロー (/speckit.plan コマンドのスコープ)
```
1. 入力パスから機能仕様を読み込み ✅
2. 技術コンテキストを記入 ✅
3. 憲章チェックセクションを評価 ✅
4. Phase 0 を実行 → research.md
5. Phase 1 を実行 → contracts, data-model.md, quickstart.md
6. 憲章チェックセクションを再評価
7. Phase 2 を計画 → タスク生成アプローチを記述
8. 停止 - /speckit.tasks コマンドの準備完了
```

## 概要

本機能は、現在の2層ブランチフロー（feature → main）を3層フロー（feature → develop → main）に変更することで、リリース頻度を削減し、リリース品質を向上させます。

**主要要件**:
- developブランチで変更を蓄積し、意図的なタイミングでmainにリリース
- feature → develop は自動マージ、develop → main は手動トリガー（/releaseコマンド）
- mainマージ時にsemantic-release、MCPサーバー（npm）、LSPサーバー（全プラットフォーム）を自動配信

**技術アプローチ**:
- GitHub Actionsワークフローの調整（auto-merge, release, unity-cli-publish）
- Bashスクリプトの修正（finish-feature.sh、新規PR移行スクリプト）
- 新規/releaseコマンドの実装（semantic-release dry-run、PR作成）

## 技術コンテキスト

**言語/バージョン**: Bash 4.x+, Node.js 18+, YAML（GitHub Actions）
**主要依存関係**:
- gh CLI（GitHub CLI）: PR操作、ブランチ操作
- semantic-release: 自動バージョニング、リリースノート生成
- npm: MCPサーバー配信
- .NET SDK 6.0+: LSPサーバービルド

**ストレージ**: N/A（ファイルシステムのみ）
**テスト**: bash-test-framework, GitHub Actions local runner（act）
**対象プラットフォーム**: Linux（CI/CD）、macOS/Linux/Windows（開発環境）
**プロジェクトタイプ**: インフラストラクチャ/CI/CD（既存リポジトリの拡張）
**パフォーマンス目標**:
- /releaseコマンド → GitHub Release作成: 30分以内
- PR自動マージ: CI/CDチェック完了後5分以内

**制約**:
- GitHub Actionsの実行時間制限（無料プランで6時間）
- semantic-releaseはConventional Commits規約に依存
- gh CLI認証が必要（`gh auth login`）

**スケール/スコープ**:
- 既存16個のfeature PR移行
- GitHub Actionsワークフロー3個の調整
- Bashスクリプト2個の修正・新規作成
- ドキュメント3個の更新

## 憲章チェック

**シンプルさ**:
- プロジェクト数: 1（既存unity-cliリポジトリの拡張）✅
- フレームワークを直接使用? はい（GitHub Actions、semantic-release、gh CLIを直接使用）✅
- 単一データモデル? N/A（インフラストラクチャ変更、データモデルなし）✅
- パターン回避? はい（Repository/UoWパターンなし、シンプルなBashスクリプト）✅

**アーキテクチャ**:
- すべての機能をライブラリとして? N/A（インフラストラクチャ変更）
- ライブラリリスト: N/A
- ライブラリごとのCLI:
  - `/release`コマンド: Claudeスラッシュコマンド（.claude/commands/release.md）
  - finish-feature.sh: 既存スクリプト、修正のみ
  - migrate-pr-to-develop.sh: 新規スクリプト、--help/--dry-run提供
- ライブラリドキュメント: CLAUDE.mdに統合（llms.txt形式ではない）

**テスト (妥協不可)**:
- RED-GREEN-Refactorサイクルを強制? はい（契約テスト → 失敗確認 → 実装）✅
- Gitコミットはテストが実装より先に表示? はい（TDD厳守）✅
- 順序: Contract→Integration→E2E→Unitを厳密に遵守? はい✅
- 実依存関係を使用? はい（実GitHub Actions、実gh CLI、実semantic-release）✅
- Integration testの対象: GitHub Actionsワークフロー、Bashスクリプト、PR操作✅
- 禁止: テスト前の実装、REDフェーズのスキップ ✅

**可観測性**:
- 構造化ロギング含む? はい（GitHub Actionsログ、スクリプトecho出力）
- フロントエンドログ → バックエンド? N/A
- エラーコンテキスト十分? はい（失敗時にPRコメント、エラーログ出力）

**バージョニング**:
- バージョン番号割り当て済み? はい（semantic-releaseが自動管理、Conventional Commits準拠）
- 変更ごとにBUILDインクリメント? はい（feat/fixコミットごとにバージョン自動更新）
- 破壊的変更を処理? はい（既存PR移行計画、テスト並列実行）

## プロジェクト構造

### ドキュメント (この機能)
```
specs/SPEC-1ac96646/
├── spec.md               # 機能仕様（完成）
├── plan.md               # このファイル（進行中）
├── research.md           # Phase 0 出力（未作成）
├── data-model.md         # Phase 1 出力（N/A - インフラ変更）
├── quickstart.md         # Phase 1 出力（未作成）
├── contracts/            # Phase 1 出力（契約テスト定義）
└── tasks.md              # Phase 2 出力（/speckit.tasksで作成）
```

### ソースコード (リポジトリルート)
```
.github/workflows/
├── auto-merge.yml        # 修正: developのみ対象
├── release.yml           # 現状維持: mainでsemantic-release
└── unity-cli-publish.yml # 現状維持: GitHub Releaseでnpm publish

.specify/scripts/bash/
├── finish-feature.sh     # 修正: --base develop
└── migrate-pr-to-develop.sh  # 新規: 既存PR移行

.claude/commands/
└── release.md            # 新規: /releaseコマンド実装

tests/
├── contracts/
│   ├── auto-merge.contract.test.sh
│   ├── release-command.contract.test.sh
│   ├── semantic-release.contract.test.sh
│   ├── mcp-publish.contract.test.sh
│   └── lsp-build.contract.test.sh
├── integration/
│   ├── full-release-cycle.test.sh
│   └── pr-migration.test.sh
└── e2e/
    └── new-feature-to-release.test.sh

CLAUDE.md                 # 修正: 3層フロー説明
README.md                 # 修正: リリースフロー図追加
```

**構造決定**: 既存リポジトリ構造を維持、新規ファイル最小限

## Phase 0: アウトライン＆リサーチ

**リサーチタスク**:

1. **GitHub Actions ブランチフィルタリング**:
   - 調査: `branches:` フィルタで複数ブランチを条件分岐する方法
   - 目的: auto-merge.ymlでdevelopのみ対象にする方法確認

2. **semantic-release ブランチ設定**:
   - 調査: `.releaserc.json`の`branches`設定とmainブランチ専用化
   - 目的: developブランチでsemantic-releaseが実行されないことを確認

3. **gh CLI PR操作**:
   - 調査: `gh pr create`の`--base`オプション、PRのベースブランチ変更方法
   - 目的: finish-feature.sh修正、PR移行スクリプト実装の前提知識

4. **Claudeスラッシュコマンド実装**:
   - 調査: `.claude/commands/*.md`のフォーマット、semantic-release dry-run実行方法
   - 目的: /releaseコマンドの実装仕様決定

5. **既存PR一括操作**:
   - 調査: `gh pr edit`でベースブランチ変更、複数PR処理のベストプラクティス
   - 目的: migrate-pr-to-develop.sh実装の設計

**出力**: `research.md`（各調査結果、決定事項、代替案の記録）

## Phase 1: 設計＆契約

**データモデル**: N/A（インフラストラクチャ変更のため、エンティティなし）

**API契約**: N/A（REST/GraphQL APIなし、CI/CDワークフローのみ）

**契約テスト** (`/contracts/`):

1. **auto-merge.contract.test.sh**:
   ```bash
   # 契約: developへのPRは自動マージ、mainへのPRは自動マージしない
   test_develop_pr_auto_merges()
   test_main_pr_does_not_auto_merge()
   test_auto_merge_waits_for_checks()
   test_auto_merge_comments_on_failure()
   ```

2. **release-command.contract.test.sh**:
   ```bash
   # 契約: /releaseコマンドがリリースノートプレビュー、PR作成
   test_release_command_exists()
   test_release_shows_preview()
   test_release_creates_pr_without_auto_merge()
   test_release_skips_if_no_changes()
   ```

3. **semantic-release.contract.test.sh**:
   ```bash
   # 契約: mainマージ時にsemantic-release実行、成果物生成
   test_semantic_release_runs_on_main_merge()
   test_package_json_updated()
   test_unity_package_version_synced()
   test_changelog_generated()
   test_tag_created()
   ```

4. **mcp-publish.contract.test.sh**:
   ```bash
   # 契約: GitHub Release時にnpm publish実行
   test_mcp_publish_on_release()
   test_version_matches_tag()
   test_npmjs_package_available()
   ```

5. **lsp-build.contract.test.sh**:
   ```bash
   # 契約: LSPサーバー全プラットフォームビルド
   test_lsp_manifest_exists()
   test_all_platforms_built()
   test_binaries_attached_to_release()
   ```

**統合テストシナリオ** (`/tests/integration/`):

1. **full-release-cycle.test.sh**:
   - feature → develop PR → 自動マージ
   - /release実行 → develop → main PR
   - PRマージ → semantic-release → MCPサーバー → LSPサーバー → GitHub Release

2. **pr-migration.test.sh**:
   - 既存mainベースPRをdevelopベースに変更
   - CI/CDチェック再実行確認
   - auto-merge動作確認

**Quickstart** (`quickstart.md`):
- developブランチ作成手順
- GitHub上でデフォルトブランチ変更手順
- /releaseコマンド使用例
- 既存PR移行手順

**エージェントファイル更新**: `CLAUDE.md`
- Worktree＆ブランチ運用セクション更新
- リリースフローセクション更新
- /releaseコマンド説明追加

**出力**: contracts/*, quickstart.md, CLAUDE.md更新

## Phase 2: タスク計画アプローチ

**タスク生成戦略**:
- Setup（5タスク）: developブランチ作成、GitHub設定、環境準備
- Test（10タスク）: 契約テスト5個、統合テスト2個、E2Eテスト1個実装
- Core（8タスク）: GitHub Actions修正、スクリプト修正/新規作成、/releaseコマンド実装
- Integration（3タスク）: CLAUDE.md更新、README.md更新、quickstart.md作成
- Polish（4タスク）: 既存PR移行、テスト検証、ドキュメント最終確認、完了確認

**順序戦略**:
- TDD順序: 契約テスト → 実装 → 統合テスト → E2Eテスト
- 依存関係順序: developブランチ作成 → ワークフロー修正 → スクリプト修正 → /releaseコマンド → PR移行
- 並列実行[P]: 契約テスト5個、ワークフロー修正3個、ドキュメント更新3個

**推定出力**: tasks.mdに30個の番号付き、順序付きタスク

**重要**: このフェーズは/speckit.tasksコマンドで実行、/speckit.planではない

## Phase 3+: 今後の実装

**Phase 3**: タスク実行 (/speckit.tasksコマンドがtasks.mdを作成)
**Phase 4**: 実装 (憲章原則に従ってtasks.mdを実行)
**Phase 5**: 検証 (テスト実行、quickstart.md実行、パフォーマンス検証)

## 複雑さトラッキング

*憲章チェックに正当化が必要な違反なし*

| 違反 | 必要な理由 | より単純な代替案が却下された理由 |
|------|-----------|--------------------------------|
| なし | - | - |

## 進捗トラッキング

**フェーズステータス**:
- [x] Phase 0: Research完了 (/speckit.plan コマンド) ✅ 2025-11-07
- [x] Phase 1: Design完了 (/speckit.plan コマンド) ✅ 2025-11-09
- [x] Phase 2: Task planning完了 (/speckit.plan コマンド - アプローチのみ記述) ✅ 2025-11-09
- [x] Phase 3: Tasks生成済み (/speckit.tasks コマンド) ✅ 2025-11-09
- [x] Phase 4: 実装完了 ✅ 2025-11-09
- [x] Phase 5: 検証合格 ✅ 2025-11-09

**ゲートステータス**:
- [x] 初期憲章チェック: 合格
- [x] 設計後憲章チェック: 合格 ✅ 2025-11-09
- [x] すべての要明確化解決済み ✅ research.md参照
- [x] 複雑さの逸脱を文書化済み（違反なし）

---
*憲章 v1.0.0 に基づく - `/docs/constitution.md` 参照*

## Tasks

# タスク: 3層リリースフロー（feature → develop → main）

**入力**: `/specs/SPEC-1ac96646/`の設計ドキュメント
**前提条件**: plan.md (必須), research.md, quickstart.md

## 実行フロー (main)
```
1. 機能ディレクトリからplan.mdを読み込み
   → 見つからない場合: ERROR "実装計画が見つかりません"
   → 抽出: 技術スタック、ライブラリ、構造
2. オプション設計ドキュメントを読み込み:
   → research.md: 決定を抽出 → setupタスク
   → quickstart.md: テストシナリオを確認
3. カテゴリ別にタスクを生成:
   → Setup: developブランチ作成、GitHub設定、環境準備
   → Tests: contract tests (5個), integration tests (2個), e2e tests (1個)
   → Core: GitHub Actionsワークフロー修正、Bashスクリプト修正/新規作成
   → Integration: ドキュメント更新、/releaseコマンド実装
   → Polish: 既存PR移行、テスト検証、完了確認
4. タスクルールを適用:
   → 異なるファイル = [P]をマーク (並列実行可能)
   → 同じファイル = 順次実行 ([P]なし)
   → テストが実装より先 (TDD)
5. タスクを順次番号付け (T001, T002...)
6. 依存関係グラフを生成
7. 並列実行例を作成
8. タスク完全性を検証
9. 戻り値: SUCCESS (タスク実行準備完了)
```

## フォーマット: `[ID] [P?] 説明`
- **[P]**: 並列実行可能 (異なるファイル、依存関係なし)
- 説明には正確なファイルパスを含める

## Phase 3.1: セットアップ (Setup)
- [ ] T001 mainブランチからdevelopブランチを作成してpush
- [ ] T002 GitHubデフォルトブランチをdevelopに変更
- [ ] T003 [P] mainブランチにBranch Protection Rules設定
- [ ] T004 [P] developブランチにBranch Protection Rules設定（オプション）
- [ ] T005 [P] gh CLI認証確認（`gh auth status`）

## Phase 3.2: テストファースト (TDD) ⚠️ 3.3の前に完了必須
**重要: これらのテストは記述され、実装前に失敗する必要がある**

### 契約テスト (Contract Tests)
- [ ] T006 [P] specs/SPEC-1ac96646/contracts/auto-merge.contract.test.sh を作成
  - test_develop_pr_auto_merges()
  - test_main_pr_does_not_auto_merge()
  - test_auto_merge_waits_for_checks()
  - test_auto_merge_comments_on_failure()
- [ ] T007 [P] specs/SPEC-1ac96646/contracts/release-command.contract.test.sh を作成
  - test_release_command_exists()
  - test_release_shows_preview()
  - test_release_creates_pr_without_auto_merge()
  - test_release_skips_if_no_changes()
- [ ] T008 [P] specs/SPEC-1ac96646/contracts/semantic-release.contract.test.sh を作成
  - test_semantic_release_runs_on_main_merge()
  - test_package_json_updated()
  - test_unity_package_version_synced()
  - test_changelog_generated()
  - test_tag_created()
- [ ] T009 [P] specs/SPEC-1ac96646/contracts/mcp-publish.contract.test.sh を作成
  - test_mcp_publish_on_release()
  - test_version_matches_tag()
  - test_npmjs_package_available()
- [ ] T010 [P] specs/SPEC-1ac96646/contracts/lsp-build.contract.test.sh を作成
  - test_lsp_manifest_exists()
  - test_all_platforms_built()
  - test_binaries_attached_to_release()

### 統合テスト (Integration Tests)
- [ ] T011 [P] tests/integration/full-release-cycle.test.sh を作成
  - feature → develop PR → 自動マージ
  - /release実行 → develop → main PR
  - PRマージ → semantic-release → MCPサーバー → LSPサーバー → GitHub Release
- [ ] T012 [P] tests/integration/pr-migration.test.sh を作成
  - 既存mainベースPRをdevelopベースに変更
  - CI/CDチェック再実行確認
  - auto-merge動作確認

### E2Eテスト (End-to-End Tests)
- [ ] T013 [P] tests/e2e/new-feature-to-release.test.sh を作成
  - 新規featureブランチ作成 → develop PR → マージ → /release → main PR → GitHub Release

## Phase 3.3: コア実装 (テストが失敗した後のみ)

### GitHub Actionsワークフロー修正
- [ ] T014 [P] .github/workflows/auto-merge.yml を修正
  - developブランチのみを対象にする（branches: [develop]）
  - mainへのPRは自動マージしない
- [ ] T015 [P] .github/workflows/release.yml を確認
  - mainブランチでのsemantic-release実行を確認
  - 変更不要なら確認のみ
- [ ] T016 [P] .github/workflows/unity-cli-publish.yml を確認
  - GitHub Release作成時のnpm publish確認
  - 変更不要なら確認のみ

### Bashスクリプト修正/新規作成
- [ ] T017 .specify/scripts/bash/finish-feature.sh を修正
  - PRベースブランチをdevelopに変更（--base develop）
  - エラーハンドリング追加
- [ ] T018 .specify/scripts/bash/migrate-pr-to-develop.sh を新規作成
  - 既存16個のfeature PRのベースブランチをdevelopに変更
  - --help, --dry-run オプション実装
  - べき等性を保証（移行済みPRスキップ）

### /releaseコマンド実装
- [ ] T019 .claude/commands/release.md を新規作成
  - semantic-release dry-runを実行してバージョン判定
  - リリースノートプレビュー表示（バージョン、CHANGELOG、成果物リスト）
  - ユーザー確認後にdevelop → main PRを作成（auto-merge無効）

## Phase 3.4: 統合 (Integration)

### ドキュメント更新
- [ ] T020 [P] CLAUDE.md を更新
  - Worktree＆ブランチ運用セクション更新（3層フロー反映）
  - リリースフローセクション更新（/releaseコマンド説明追加）
  - 自動リリース（semantic-release）セクション更新
- [ ] T021 [P] README.md を更新
  - リリースフロー図追加（3層ブランチ構造）
  - developブランチ説明追加
  - /releaseコマンド使用例追加
- [ ] T022 [P] specs/SPEC-1ac96646/quickstart.md を確認
  - 既に作成済み、内容確認のみ
  - 不足があれば追記

## Phase 3.5: 仕上げ (Polish)

### 既存PR移行
- [ ] T023 .specify/scripts/bash/migrate-pr-to-develop.sh を実行
  - --dry-run で移行対象PR確認
  - 実行して16個のPRをdevelopベースに変更
  - 移行後のCI/CDチェック成功確認

### テスト検証
- [ ] T024 契約テスト5個を実行して合格確認
  - auto-merge.contract.test.sh
  - release-command.contract.test.sh
  - semantic-release.contract.test.sh
  - mcp-publish.contract.test.sh
  - lsp-build.contract.test.sh
- [ ] T025 統合テスト2個を実行して合格確認
  - full-release-cycle.test.sh
  - pr-migration.test.sh
- [ ] T026 E2Eテスト1個を実行して合格確認
  - new-feature-to-release.test.sh

### 最終確認
- [ ] T027 パフォーマンス検証
  - /releaseコマンド → GitHub Release作成: 30分以内
  - PR自動マージ: CI/CDチェック完了後5分以内
- [ ] T028 ドキュメント整合性確認
  - CLAUDE.md、README.md、quickstart.mdが3層フローを正確に反映
  - 開発者が迷わずフローを理解できるか確認
- [ ] T029 成功基準達成確認
  - リリース頻度の削減: GitHub Release作成間隔が平均7日以上
  - 自動マージ成功率: 95%以上
  - リリース成果物の完全性: 100%
- [ ] T030 SPEC-1ac96646ステータスを「実装完了」に更新

## 依存関係
- Setup (T001-T005) が Tests (T006-T013) と Core (T014-T019) より先
- Tests (T006-T013) が Core (T014-T019) より先 (TDD)
- Core (T014-T019) が Integration (T020-T022) より先
- Integration (T020-T022) が Polish (T023-T030) より先
- T001 が T002, T003, T004 をブロック
- T006-T010 が T014-T019 をブロック
- T014-T019 が T023 をブロック

## 並列実行例
```
# T003-T005 を一緒に起動:
Task: "mainブランチにBranch Protection Rules設定"
Task: "developブランチにBranch Protection Rules設定"
Task: "gh CLI認証確認"

# T006-T010 を一緒に起動:
Task: "specs/SPEC-1ac96646/contracts/auto-merge.contract.test.sh を作成"
Task: "specs/SPEC-1ac96646/contracts/release-command.contract.test.sh を作成"
Task: "specs/SPEC-1ac96646/contracts/semantic-release.contract.test.sh を作成"
Task: "specs/SPEC-1ac96646/contracts/mcp-publish.contract.test.sh を作成"
Task: "specs/SPEC-1ac96646/contracts/lsp-build.contract.test.sh を作成"

# T011-T013 を一緒に起動:
Task: "tests/integration/full-release-cycle.test.sh を作成"
Task: "tests/integration/pr-migration.test.sh を作成"
Task: "tests/e2e/new-feature-to-release.test.sh を作成"

# T014-T016 を一緒に起動:
Task: ".github/workflows/auto-merge.yml を修正"
Task: ".github/workflows/release.yml を確認"
Task: ".github/workflows/unity-cli-publish.yml を確認"

# T020-T022 を一緒に起動:
Task: "CLAUDE.md を更新"
Task: "README.md を更新"
Task: "specs/SPEC-1ac96646/quickstart.md を確認"
```

## 注意事項
- [P] タスク = 異なるファイル、依存関係なし
- 実装前にテストが失敗することを確認 (TDD厳守)
- 各タスク後にコミット (Conventional Commits規約)
- 回避: 曖昧なタスク、同じファイルの競合

## タスク生成ルール
*main()実行中に適用*

1. **Contractsから**:
   - 各contractファイル → contract testタスク [P]
   - 各endpoint/workflow → 実装タスク

2. **User Storiesから**:
   - 各story → integration test [P]
   - クイックスタートシナリオ → 検証タスク

3. **順序**:
   - Setup → Tests → Core → Integration → Polish
   - 依存関係は並列実行をブロック

## 検証チェックリスト
*ゲート: 戻る前にmain()でチェック*

- [x] すべてのcontractsに対応するテストがある (T006-T010)
- [x] すべてのテストが実装より先にある (T006-T013 → T014-T019)
- [x] 並列タスクは本当に独立している ([P]マーク確認済み)
- [x] 各タスクは正確なファイルパスを指定
- [x] 同じファイルを変更する[P]タスクがない

## TDD

_TODO_

## Research

# Phase 0: リサーチ＆技術調査

**SPEC ID**: SPEC-1ac96646
**日付**: 2025-11-07
**ステータス**: 完了

## 概要

本ドキュメントは、3層リリースフロー（feature → develop → main）実装に必要な技術調査結果をまとめたものです。

---

## 1. GitHub Actions ブランチフィルタリング

### 調査内容
`branches:` フィルタで複数ブランチを条件分岐する方法を調査。

### 調査結果

**現状（auto-merge.yml）**:
```yaml
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches:
      - main
      - develop
```

**分析**:
- `branches:` は**PRのベースブランチ（マージ先）**を指定
- 現在はmainとdevelopの両方でトリガー
- ジョブ内で条件分岐する場合は`if:`を使用可能

### 決定事項

**オプションA: ワークフロー分離（推奨）**
- developブランチのみ自動マージ
- mainブランチは除外

```yaml
on:
  pull_request:
    branches:
      - develop  # mainを削除
```

**理由**:
- シンプル（条件分岐不要）
- 意図が明確（developのみ自動マージ）
- mainへのPRは手動承認を強制

**オプションB: 条件分岐**
```yaml
branches:
  - main
  - develop

jobs:
  auto-merge:
    if: github.event.pull_request.base.ref == 'develop'
```

**却下理由**:
- 複雑化（条件ロジック追加）
- mainブランチへのPRで無駄にワークフロー起動

---

## 2. semantic-release ブランチ設定

### 調査内容
`.releaserc.json`の`branches`設定とmainブランチ専用化を確認。

### 調査結果

**現状（.releaserc.json）**:
```json
{
  "branches": ["main"],
  "tagFormat": "v${version}",
  "plugins": [...]
}
```

**分析**:
- `branches: ["main"]`で既にmainブランチ専用
- developブランチでsemantic-releaseは実行されない
- release.ymlは`on.push.branches: [main]`でトリガー

### 決定事項

**変更不要**:
- `.releaserc.json`は現状維持
- `branches: ["main"]`のまま
- release.ymlも`branches: [main]`を維持

**理由**:
- 既に要件を満たしている
- mainへのpushでのみsemantic-release実行
- developブランチは除外済み

---

## 3. gh CLI PR操作

### 調査内容
`gh pr create`の`--base`オプション、PRのベースブランチ変更方法を調査。

### 調査結果

**PR作成（finish-feature.sh）**:
```bash
gh pr create --base main --head "$CURRENT_BRANCH" --title "$PR_TITLE" --body "$PR_BODY"
```

**ベースブランチ変更（PR移行）**:
```bash
gh pr edit <PR番号> --base develop
```

**PRリスト取得**:
```bash
# mainベースのPR一覧
gh pr list --base main --json number,title,headRefName

# すべてのPR一覧
gh pr list --state open --json number,title,baseRefName,headRefName
```

### 決定事項

**finish-feature.sh修正**:
```bash
# 変更前
gh pr create --base main ...

# 変更後
gh pr create --base develop ...
```

**PR移行スクリプト（migrate-pr-to-develop.sh）**:
```bash
#!/bin/bash
# 既存16個のPRをdevelopベースに一括変更

set -euo pipefail

# mainベースのPR取得
pr_list=$(gh pr list --base main --json number,title,headRefName)
pr_count=$(echo "$pr_list" | jq '. | length')

echo "Found $pr_count PRs with base=main"

# 各PRをdevelopベースに変更
echo "$pr_list" | jq -r '.[] | @json' | while IFS= read -r pr_json; do
  pr_number=$(echo "$pr_json" | jq -r '.number')
  pr_title=$(echo "$pr_json" | jq -r '.title')

  echo "Migrating PR #$pr_number: $pr_title"
  gh pr edit "$pr_number" --base develop
done

echo "Migration complete!"
```

**代替案（検討したが却下）**:
- **手動変更**: エラーの可能性、時間がかかる
- **GitHub API直接呼び出し**: gh CLIで十分、複雑化

---

## 4. Claudeスラッシュコマンド実装

### 調査内容
`.claude/commands/*.md`のフォーマット、semantic-release dry-run実行方法を調査。

### 調査結果

**スラッシュコマンドフォーマット**:
```markdown
---
description: コマンドの説明（1行）
---

## ユーザー入力

```text
$ARGUMENTS
```

## 説明

コマンドの目的と実行内容

## 実行手順

1. ステップ1
2. ステップ2
...
```

**semantic-release dry-run**:
```bash
# dry-runでリリースノートプレビュー
npx semantic-release --dry-run --no-ci

# 出力例:
# [semantic-release] › ℹ  The next release version is 2.17.0
# [semantic-release] › ℹ  Release note for version 2.17.0:
# ## [2.17.0] (2025-11-07)
# ### Features
# * Add video capture support
```

### 決定事項

**/releaseコマンド仕様**:

**ファイル**: `.claude/commands/release.md`

**処理フロー**:
1. developとmainの差分確認（`git log main..develop --oneline`）
2. 差分がなければスキップ、メッセージ表示
3. semantic-release dry-run実行、リリースノートプレビュー取得
4. ユーザーに確認プロンプト表示
5. 確認後、develop → main PR作成（`gh pr create --base main --head develop`）
6. PRボディにリリースノート、成果物リスト、マージ後の自動フロー説明

**代替案（検討したが却下）**:
- **PRの自動マージ**: 手動承認を残すべき（リリースは慎重に）
- **mainへの直接push**: PRレビューフローを尊重すべき

---

## 5. 既存PR一括操作

### 調査内容
`gh pr edit`でベースブランチ変更、複数PR処理のベストプラクティスを調査。

### 調査結果

**PR情報取得**:
```bash
# JSON形式で取得（処理しやすい）
gh pr list --base main --json number,title,headRefName,url

# 出力例:
# [
#   {"number": 15, "title": "Add feature X", "headRefName": "feature/SPEC-12345678", "url": "..."},
#   {"number": 16, "title": "Fix bug Y", "headRefName": "feature/SPEC-87654321", "url": "..."}
# ]
```

**ベースブランチ変更**:
```bash
# 単一PR
gh pr edit 15 --base develop

# エラーハンドリング
if gh pr edit "$pr_number" --base develop; then
  echo "✅ PR #$pr_number migrated successfully"
else
  echo "❌ Failed to migrate PR #$pr_number"
fi
```

**べき等性保証**:
```bash
# 既にdevelopベースの場合はスキップ
current_base=$(gh pr view "$pr_number" --json baseRefName --jq '.baseRefName')
if [ "$current_base" = "develop" ]; then
  echo "⏭️ PR #$pr_number already targets develop, skipping"
  continue
fi
```

### 決定事項

**migrate-pr-to-develop.sh 仕様**:

**機能**:
- mainベースのPRを一括取得
- 各PRのベースブランチをdevelopに変更
- べき等性保証（既にdevelopベースならスキップ）
- エラーハンドリング（失敗時もログ記録、続行）
- dry-runモード（`--dry-run`で実行せず表示のみ）

**オプション**:
- `--help`: ヘルプ表示
- `--dry-run`: 変更せずに対象PRリスト表示
- `--verbose`: 詳細ログ出力

**代替案（検討したが却下）**:
- **GitHub Web UIで手動変更**: 16個は多すぎる、エラーの可能性
- **GitHub GraphQL Mutation**: gh CLI RESTで十分、複雑化

---

## まとめ

### 技術スタック（確定）
- **GitHub Actions**: YAML設定、既存ワークフロー修正のみ
- **semantic-release**: 現状維持（.releaserc.json変更不要）
- **gh CLI**: PR操作（create、edit、list、view）
- **Bash**: スクリプト実装（finish-feature.sh修正、migrate-pr-to-develop.sh新規）
- **Markdown**: /releaseコマンド実装

### 変更が必要なファイル
1. `.github/workflows/auto-merge.yml`: `branches: [develop]`のみ
2. `.specify/scripts/bash/finish-feature.sh`: `--base develop`に変更
3. `.specify/scripts/bash/migrate-pr-to-develop.sh`: 新規作成
4. `.claude/commands/release.md`: 新規作成
5. `CLAUDE.md`: ブランチフロー説明更新
6. `README.md`: リリースフロー図追加

### 変更不要なファイル
- `.releaserc.json`: 既にmainブランチ専用
- `.github/workflows/release.yml`: mainへのpushでトリガー済み
- `.github/workflows/unity-cli-publish.yml`: GitHub Release作成時にトリガー（ブランチ非依存）
- `.github/workflows/release-lsp.yml`: タグpush時にトリガー（ブランチ非依存）

**補足説明**:
- **unity-cli-publish.yml**: `on.release.types: [published]`でトリガー。semantic-releaseがmainでGitHub Releaseを作成するため、develop/mainフロー導入後も正常動作。変更不要。
- **release-lsp.yml**: `on.push.tags: ['v*']`でトリガー。semantic-releaseがmainでタグ（v*）を作成するため、develop/mainフロー導入後も正常動作。変更不要。

### リスク＆対策
| リスク | 対策 |
|--------|------|
| 既存PR移行時のエラー | べき等性保証、エラーハンドリング、dry-runモード |
| mainへのPRが誤って自動マージ | auto-merge.ymlでmainを除外、契約テストで検証 |
| semantic-releaseがdevelopで実行 | branches設定で既に防止済み、テストで確認 |
| /releaseコマンド実行ミス | dry-runプレビュー、ユーザー確認プロンプト |

---

## 次のステップ

Phase 1（設計＆契約）に進む準備完了:
- すべての技術的不明点を解決
- 実装方針決定
- 変更対象ファイル特定

✅ **Phase 0完了**

## Data Model

# データモデル: 3層リリースフロー

**機能ID**: `SPEC-1ac96646` | **日付**: 2025-11-07 | **仕様**: [spec.md](./spec.md)

## 概要

本機能はインフラストラクチャ変更（CI/CDワークフロー、ブランチ戦略）のため、従来のエンティティ・リレーションシップモデルではなく、**ワークフロー状態**と**Git操作のデータフロー**をモデル化します。

## ブランチモデル

### ブランチ構造

```
main (安定版リリース専用)
  ↑ (手動マージ、PR必須)
develop (統合ブランチ、デフォルトブランチ)
  ↑ (自動マージ、CI/CD成功時)
feature/SPEC-xxxxxxxx (機能開発ブランチ)
```

### ブランチ状態遷移

```
[feature作成] → [開発] → [finish-feature.sh実行]
                             ↓
                    [PR作成: feature→develop]
                             ↓
                    [CI/CDチェック実行]
                        ↙         ↘
                [成功]              [失敗]
                  ↓                   ↓
            [自動マージ]          [コメント通知]
                  ↓
          [developに統合]
                  ↓
          [変更蓄積 (複数feature)]
                  ↓
          [/release実行]
                  ↓
        [semantic-release dry-run]
                  ↓
        [リリースノートプレビュー]
                  ↓
        [PR作成: develop→main]
                  ↓
          [手動レビュー・承認]
                  ↓
          [mainにマージ]
                  ↓
        [semantic-release実行]
                  ↓
        [GitHub Release作成]
            ↙         ↘
    [npm publish]  [LSPビルド]
```

## ワークフロー状態モデル

### PR状態 (Pull Request State)

```yaml
PullRequest:
  id: string                    # PR番号 (例: "65")
  title: string                 # PRタイトル
  source_branch: string         # feature/SPEC-xxxxxxxx
  target_branch: string         # develop | main
  status: enum                  # open | merged | closed
  auto_merge_enabled: boolean   # developへのPRのみtrue
  ci_status: enum               # pending | success | failure
  created_at: datetime
  merged_at: datetime | null
```

**状態遷移**:

```
[open] → [CI pending]
         ↓
      [CI success] → (developベース) → [auto-merge] → [merged]
         |           (mainベース)   → [manual review] → [merged]
         ↓
      [CI failure] → [comment added] → [open (待機)]
```

### リリース状態 (Release State)

```yaml
Release:
  version: string               # semantic-releaseが決定 (例: "2.32.0")
  tag: string                   # vX.Y.Z (例: "v2.32.0")
  branch: string                # main
  changelog: string             # CHANGELOG.mdの内容
  artifacts:
    mcp_server:
      npm_published: boolean
      npm_url: string           # https://www.npmjs.com/package/...
    lsp_server:
      platforms:
        - rid: string           # linux-x64, osx-x64, ...
          binary_path: string   # GitHub Release添付URL
          build_status: enum    # success | failure
    unity_package:
      version_synced: boolean
      package_json_path: string
  created_at: datetime
  status: enum                  # draft | published | failed
```

**状態遷移**:

```
[/release実行] → [dry-run]
                   ↓
              [version算出]
                   ↓
              [プレビュー表示]
                   ↓
              [PR作成: develop→main]
                   ↓
              [手動マージ]
                   ↓
              [semantic-release実行]
                   ↓
              [GitHub Release draft作成]
                   ↓
          [npm publish] + [LSPビルド (並列)]
                   ↓
              [Release published]
```

### ワークフロージョブ状態 (Workflow Job State)

```yaml
WorkflowJob:
  workflow_name: string         # auto-merge.yml | release.yml | publish.yml
  run_id: string                # GitHub Actions Run ID
  trigger: enum                 # push | pull_request | release
  branch: string                # develop | main
  status: enum                  # queued | in_progress | success | failure
  steps:
    - name: string
      status: enum              # success | failure | skipped
      duration_seconds: number
  started_at: datetime
  completed_at: datetime | null
  logs_url: string              # GitHub Actions ログURL
```

## コマンド入出力モデル

### /release コマンド

**入力**: なし（現在のdevelopブランチ状態を使用）

**処理フロー**:

```bash
1. git fetch --tags origin
2. semantic-release --dry-run --no-ci
   ↓
3. バージョン番号抽出 (例: 2.33.0)
4. CHANGELOG生成プレビュー
5. 成果物リスト生成
   ↓
6. ユーザーにプレビュー表示
   ↓
7. release/vX.Y.Z ブランチ作成
8. gh pr create --base main --head release/vX.Y.Z
```

**出力**:

```yaml
ReleasePreview:
  next_version: string          # "2.33.0"
  current_version: string       # "2.32.0"
  version_bump: enum            # major | minor | patch
  changelog_preview: string     # マークダウン形式
  artifacts:
    - unity-cli (npm)
    - lsp-server (6 platforms)
    - Unity Package
    - CHANGELOG.md
  pr_url: string | null         # PRが作成された場合のURL
  skipped: boolean              # 変更なしの場合true
  skip_reason: string | null    # "No changes since last release"
```

### finish-feature.sh コマンド

**入力**:

```bash
--base <branch>     # develop (デフォルト)
--draft             # ドラフトPRとして作成
```

**処理フロー**:

```bash
1. 現在のブランチ取得 (feature/SPEC-xxxxxxxx)
2. git push origin <current_branch>
3. gh pr create --base develop --fill
   ↓
4. auto-merge有効化 (--draftでない場合)
```

**出力**:

```yaml
FeatureFinish:
  branch: string                # feature/SPEC-xxxxxxxx
  pr_number: string             # "66"
  pr_url: string                # https://github.com/.../pull/66
  auto_merge_enabled: boolean   # true | false
  base_branch: string           # develop
```

## GitHub Actions イベントモデル

### auto-merge.yml トリガー

```yaml
Trigger:
  event: pull_request
  action: [opened, synchronize, reopened]
  branches: [develop]           # mainは除外
  conditions:
    - statusCheckRollup == "success"
```

### release.yml トリガー

```yaml
Trigger:
  event: push
  branches: [main, "release/**"]
  conditions:
    - semantic-release dry-runでバージョン決定可能
```

### publish.yml トリガー

```yaml
Trigger:
  event: release
  types: [published]
  conditions:
    - tagがv*形式
```

## データフロー図

### 完全リリースサイクル

```
[開発者] → [feature開発]
             ↓
         [finish-feature.sh]
             ↓
         [GitHub: PR作成]
             ↓
         [GitHub Actions: CI/CD]
             ↓
         [auto-merge.yml: マージ]
             ↓
         [develop: 変更蓄積]
             ↓
[リリース担当] → [/release実行]
             ↓
         [semantic-release: dry-run]
             ↓
         [プレビュー表示]
             ↓
         [GitHub: PR作成 (develop→main)]
             ↓
         [手動レビュー]
             ↓
         [mainマージ]
             ↓
         [release.yml: semantic-release実行]
             ↓
         [package.json更新]
         [CHANGELOG.md生成]
         [タグ作成]
             ↓
         [GitHub Release作成]
             ↓
         [publish.yml: 並列実行]
            ↙              ↘
    [npm publish]    [LSPビルド (6 platforms)]
         ↓                  ↓
    [npmjs.com]      [GitHub Release添付]
```

## エラー状態モデル

### PR自動マージ失敗

```yaml
AutoMergeFailure:
  pr_number: string
  failure_reason: enum
    - ci_check_failed
    - merge_conflict
    - approval_required
    - network_error
  recovery_action: enum
    - notify_comment          # PRにコメント追加
    - disable_auto_merge      # 自動マージ無効化
    - manual_intervention     # 手動介入必要
  notified_at: datetime
```

### semantic-release失敗

```yaml
SemanticReleaseFailure:
  run_id: string
  failure_stage: enum
    - version_calculation     # バージョン決定失敗
    - changelog_generation    # CHANGELOG生成失敗
    - git_push                # タグpush失敗
    - npm_publish             # npm publish失敗
  error_message: string
  recovery_action: enum
    - retry                   # リトライ
    - manual_fix              # 手動修正必要
  logs_url: string
```

### LSPビルド部分失敗

```yaml
LspBuildPartialFailure:
  platforms_success: [string]   # ["linux-x64", "osx-x64"]
  platforms_failure: [string]   # ["win-x64"]
  failure_details:
    - platform: string
      error_message: string
      build_log_url: string
  recovery_action: enum
    - attach_partial          # 成功分のみ添付
    - rebuild_failed          # 失敗分のみリビルド
```

## 制約とバリデーション

### ブランチ命名規則

```yaml
BranchNaming:
  feature: "feature/SPEC-[a-f0-9]{8}"
  release: "release/v[0-9]+\\.[0-9]+\\.[0-9]+"
  main: "main"
  develop: "develop"
```

### バージョン形式

```yaml
VersionFormat:
  pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
  example: "2.32.0"
  tag_pattern: "^v[0-9]+\\.[0-9]+\\.[0-9]+$"
  tag_example: "v2.32.0"
```

### Conventional Commits

```yaml
CommitMessage:
  pattern: "^(feat|fix|chore|docs|test|refactor)(\$[a-z]+\$)?: .+$"
  version_bump:
    "feat:": minor
    "fix:": patch
    "feat!:": major
    "BREAKING CHANGE:": major
```

## 永続化

### Git リポジトリ (ソース・オブ・トゥルース)

- **ブランチ**: develop, main, feature/*, release/*
- **タグ**: v*
- **コミット履歴**: Conventional Commits準拠

### GitHub (メタデータ)

- **Pull Requests**: PR状態、CI/CD結果、コメント
- **Releases**: バージョン、CHANGELOG、成果物添付
- **Actions**: ワークフロー実行ログ

### npm (配信)

- **パッケージ**: @akiojin/unity-cli
- **バージョン履歴**: npmjs.com

### ローカルファイル (一時)

- **.git/**: ローカルブランチ、リモート追跡
- **CHANGELOG.md**: 自動生成、Gitコミット対象
- **package.json**: バージョン番号、semantic-releaseが更新

---

**注**: 本データモデルはステートフルなエンティティではなく、Git/GitHub/CI/CDの状態遷移とデータフローを表現しています。インフラストラクチャ変更の性質上、RDBやORMは使用せず、Gitリポジトリ自体がデータストアとなります。

## Quickstart

# クイックスタートガイド: 3層リリースフロー

**SPEC ID**: SPEC-1ac96646
**日付**: 2025-11-07

## 概要

このガイドでは、3層リリースフロー（feature → develop → main）の初期セットアップと使用方法を説明します。

---

## 初期セットアップ

### 1. developブランチ作成

mainブランチから新しいdevelopブランチを作成します：

```bash
# mainブランチをpullして最新化
git checkout main
git pull origin main

# developブランチを作成してpush
git checkout -b develop
git push -u origin develop
```

### 2. GitHubデフォルトブランチ変更

gh CLIでデフォルトブランチをdevelopに変更：

```bash
# デフォルトブランチをdevelopに設定
gh repo edit --default-branch develop
```

**または GitHub Web UI**:

1. リポジトリページ → **Settings**
2. 左メニュー → **Branches**
3. **Default branch** セクション → スイッチアイコンをクリック
4. `develop` を選択 → **Update**
5. 確認ダイアログで **I understand, update the default branch** をクリック

これにより、新規PRのデフォルトベースがdevelopになります。

### 3. Branch Protection Rules設定（重要）

develop → main の自動マージを有効化するため、mainブランチにRequired status checksを設定：

```bash
# mainブランチのBranch Protection Rules設定
gh api repos/{owner}/{repo}/branches/main/protection \
  -X PUT \
  --input - <<EOF
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["test"]
  },
  "enforce_admins": false,
  "required_pull_request_reviews": null,
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}
EOF
```

**{owner}と{repo}を実際の値に置き換えてください**（例: `akiojin/unity-cli`）

**設定内容**:
- `required_status_checks.contexts: ["test"]`: testチェックが必須
- `strict: true`: PRブランチがベースブランチの最新であることを要求
- `enforce_admins: false`: 管理者は制限をバイパス可能
- `required_pull_request_reviews: null`: レビュー不要
- `allow_force_pushes: false`: force pushを禁止

**developブランチも同様に設定（オプション）**:

```bash
# developブランチのBranch Protection Rules設定
gh api repos/{owner}/{repo}/branches/develop/protection \
  -X PUT \
  --input - <<EOF
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["test"]
  },
  "enforce_admins": false,
  "required_pull_request_reviews": null,
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}
EOF
```

### 4. 既存PRの移行（オプション）

既にmainベースのPRが存在する場合、developベースに変更します：

**手動変更（PR数が少ない場合）**:

1. PR詳細ページを開く
2. ベースブランチ横の **Edit** をクリック
3. `develop` を選択
4. PRが更新される

**一括変更（PR数が多い場合）**:

```bash
# migrate-pr-to-develop.shスクリプトを使用（今後実装予定）
.specify/scripts/bash/migrate-pr-to-develop.sh

# または手動で各PRを変更
gh pr list --base main --json number | jq -r '.[].number' | while read pr_number; do
  gh pr edit "$pr_number" --base develop
done
```

---

## 通常の開発フロー

### 1. 新機能開発開始

```bash
# 仕様書作成（自動的にfeatureブランチ＆Worktree作成）
/speckit.specify

# Worktreeに移動
cd .worktrees/SPEC-xxxxxxxx/

# 実装計画作成
/speckit.plan

# タスク分解
/speckit.tasks
```

### 2. 実装とコミット

```bash
# TDDサイクル厳守（RED-GREEN-REFACTOR）
# テスト作成 → 実装 → リファクタリング

# 各変更をコミット
git add .
git commit -m "feat: 機能Xを実装"
```

### 3. PR作成＆自動マージ（developへ）

```bash
# finish-featureスクリプト実行
.specify/scripts/bash/finish-feature.sh

# 自動実行される処理:
# 1. featureブランチをリモートにpush
# 2. GitHub PR作成（ベース: develop）
# 3. GitHub Actions Required Checks監視
# 4. すべてのチェック成功 → 自動的にdevelopへマージ
```

**ドラフトPR（自動マージしたくない場合）**:

```bash
.specify/scripts/bash/finish-feature.sh --draft
```

---

## リリースフロー（develop → main）

### 1. リリース準備

developブランチに複数のfeatureが蓄積された時点でリリースを実行します。

```bash
# /releaseコマンド実行
/release
```

### 2. リリースコマンドの処理フロー

`/release`コマンドは以下を自動実行します：

**Step 1: 差分確認**
```bash
# developとmainの差分を表示
git log origin/main..origin/develop --oneline
```

差分がない場合はスキップメッセージを表示して終了。

**Step 2: リリースノートプレビュー**
```bash
# semantic-release dry-runでリリース内容を取得
cd unity-cli && npx semantic-release --dry-run --no-ci
```

出力例：
```
[semantic-release] › ℹ  The next release version is 2.17.0
[semantic-release] › ℹ  Release note for version 2.17.0:
## [2.17.0] (2025-11-07)

### Features
* Add video capture support
* Implement 3-tier release flow
```

**Step 3: ユーザー確認プロンプト**

```markdown
## 🚀 リリース準備完了

**次のバージョン**: v2.17.0

**リリース内容**:
## [2.17.0] (2025-11-07)

### Features
* Add video capture support
* Implement 3-tier release flow

**リリース成果物**:
- ✅ MCPサーバー（npm） → npmjs.comに自動publish
- ✅ LSPサーバー（全プラットフォーム） → GitHub Releaseに添付
- ✅ Unity Package → バージョン同期
- ✅ CHANGELOG.md → 自動生成

**マージ後の自動フロー**:
1. semantic-release実行 → バージョンアップ＆タグ作成
2. GitHub Release作成
3. MCPサーバー npm publish
4. LSPサーバービルド（全プラットフォーム）

---

このリリースを実行しますか？ (yes/no)
```

**Step 4: develop → main PR作成**

ユーザーが `yes` を入力すると、PRを自動作成：

```bash
gh pr create --base main --head develop \
  --title "release: v2.17.0" \
  --body "## 🚀 リリース: v2.17.0

このPRは、developブランチの変更をmainブランチにリリースします。

---

## 📋 リリース内容

$(git log origin/main..origin/develop --oneline)

---

## 🎯 リリースノート

[semantic-release dry-runの結果を挿入]

---

## 🤖 自動リリースフロー

このPRをマージすると、以下が自動的に実行されます：

1. **semantic-release**: package.json、Unity Package、CHANGELOG.mdを更新、タグ作成
2. **GitHub Release**: リリースノートと共にリリース作成
3. **npm publish**: MCPサーバーをnpmjs.comに公開
4. **LSPサーバービルド**: 全プラットフォーム（linux-x64, osx-x64, osx-arm64, win-x64）でビルド、GitHub Releaseに添付

---

⚠️ **重要**: このPRは自動マージされません。手動でレビュー＆承認が必要です。

📝 **仕様**: specs/SPEC-1ac96646/spec.md を参照してください。"
```

**Step 5: 完了メッセージ**

```markdown
✅ リリースPRが作成されました！

**PR URL**: https://github.com/akiojin/unity-cli/pull/XX

**次のステップ**:
1. PRをレビュー
2. CI/CDチェックの完了を待機
3. PRをマージ → 自動リリース開始

**マージ後の成果物**:
- npmjs.com: @akiojin/unity-cli v2.17.0
- GitHub Release: v2.17.0（LSPバイナリ添付）
- CHANGELOG.md: 自動更新

🎉 リリース準備完了です！
```

### 3. PRマージとリリース実行（自動）

1. PRのCI/CDチェック（Required checks）の完了を待機
2. すべてのRequired checks成功 → **自動的にmainへマージ**
3. マージ後、自動的にsemantic-releaseが実行される
4. GitHub Releaseが作成され、LSPバイナリが添付される
5. MCPサーバーがnpmjs.comに公開される

**注**: 手動マージは不要です。Required checksが通れば自動マージされます。

---

## トラブルシューティング

### developとmainに差分がない

```
ℹ️  developとmainに差分がありません。
リリースする変更がないため、PR作成をスキップします。

developブランチに新しい機能をマージしてから、再度/releaseを実行してください。
```

→ featureブランチを開発してdevelopにマージしてから再実行

### semantic-release dry-run失敗

```
❌ semantic-release dry-runが失敗しました。

原因:
- Conventional Commits規約に準拠していないコミットがある可能性
- package.jsonやnode_modulesに問題がある可能性

対策:
1. developブランチのコミットメッセージを確認
2. unity-cliディレクトリで `npm ci` を実行
3. エラーログを確認
```

→ Conventional Commits形式を確認（`feat:`, `fix:`, `chore:` 等）

### gh CLI認証エラー

```
❌ GitHub CLI認証エラー

以下のコマンドで認証してください:
gh auth login
```

→ `gh auth login` を実行してGitHub CLIを認証

### PRが自動マージされない

**原因と対策**:

1. **Branch Protection Rulesが未設定**
   ```bash
   # mainブランチのProtection Rules確認
   gh api repos/{owner}/{repo}/branches/main/protection

   # 設定されていない場合は初期セットアップの手順3を実行
   ```

2. **Required checksが失敗している**
   ```bash
   # PRのチェック状態確認
   gh pr checks <PR番号>

   # 失敗しているチェックを修正してpush
   ```

3. **PRがdraftモード**
   ```bash
   # draft状態を解除
   gh pr ready <PR番号>
   ```

4. **GitHub Actions権限不足**
   - リポジトリ設定 → Actions → General → Workflow permissions
   - "Read and write permissions"を選択

---

## 参考資料

- **仕様書**: `specs/SPEC-1ac96646/spec.md`
- **実装計画**: `specs/SPEC-1ac96646/plan.md`
- **技術調査**: `specs/SPEC-1ac96646/research.md`
- **/releaseコマンド**: `.claude/commands/release.md`
- **finish-featureスクリプト**: `.specify/scripts/bash/finish-feature.sh`
- **auto-mergeワークフロー**: `.github/workflows/auto-merge.yml`

---

## よくある質問

**Q: なぜ3層フローにしたの？**

A: 以前のfeature → mainフローでは、featureがマージされるたびにリリースが実行され、リリース頻度が高すぎました。3層フローでは、developで複数のfeatureを蓄積してからmainにリリースできます。

**Q: developブランチの役割は？**

A: 統合ブランチとして機能します。複数のfeatureブランチをdevelopにマージして統合テストを実行し、問題がなければmainにリリースします。

**Q: mainブランチの役割は？**

A: リリースブランチとして機能します。mainへのマージでsemantic-releaseが実行され、npm publish、GitHub Release作成、LSPビルドが自動実行されます。

**Q: 既存のfeatureブランチはどうなる？**

A: 既存のfeatureブランチはそのまま使用できます。PRのベースブランチをdevelopに変更するだけです。

**Q: semantic-releaseはいつ実行される？**

A: mainブランチへのpushでのみ実行されます。developへのマージでは実行されません（`.releaserc.json`の`branches: ["main"]`設定により）。

**Q: リリース頻度はどれくらい？**

A: プロジェクトの判断に依存します。developに複数のfeatureが蓄積された時点で `/release` を実行してください。週次、月次、機能区切りなど、チームの方針に従ってください。

## Contracts

Migrated from local files. See artifact comments below.

## Checklists

Artifact files under `checklists/` are managed in issue comments with `checklist:<name>` entries.

## Acceptance Checklist

- [ ] Add acceptance checklist

リスク	対策
既存PR移行時のエラー	べき等性保証、エラーハンドリング、dry-runモード
mainへのPRが誤って自動マージ	auto-merge.ymlでmainを除外、契約テストで検証
semantic-releaseがdevelopで実行	branches設定で既に防止済み、テストで確認
/releaseコマンド実行ミス	dry-runプレビュー、ユーザー確認プロンプト

機能仕様書: 4層リリースフロー（feature → develop → release/* → main） #69

Description

Spec

機能仕様書: 4層リリースフロー（feature → develop → release/* → main）

ユーザーシナリオ＆テスト (必須)

ユーザーストーリー1 - developブランチへのPR自動マージ (優先度: P1)

ユーザーストーリー2 - /releaseコマンドによる手動リリース (優先度: P2)

ユーザーストーリー3 - 自動リリース成果物配信 (優先度: P3)

ユーザーストーリー4 - 既存PR移行 (優先度: P4)

ユーザーストーリー5 - OpenUPM自動配信 (優先度: P5)

エッジケース

要件 (必須)

機能要件

主要エンティティ

スコープ外 (オプション)

技術制約 (該当する場合)

前提条件 (該当する場合)

依存関係 (該当する場合)

成功基準 (必須)

⚡ クイックガイドライン

Plan

実装計画: 3層リリースフロー（feature → develop → main）

実行フロー (/speckit.plan コマンドのスコープ)

概要

技術コンテキスト

憲章チェック

プロジェクト構造

ドキュメント (この機能)

ソースコード (リポジトリルート)

Phase 0: アウトライン＆リサーチ

Phase 1: 設計＆契約

Phase 2: タスク計画アプローチ

Phase 3+: 今後の実装

複雑さトラッキング

進捗トラッキング

Tasks

タスク: 3層リリースフロー（feature → develop → main）

実行フロー (main)

フォーマット: [ID] [P?] 説明

Phase 3.1: セットアップ (Setup)

Phase 3.2: テストファースト (TDD) ⚠️ 3.3の前に完了必須

契約テスト (Contract Tests)

統合テスト (Integration Tests)

E2Eテスト (End-to-End Tests)

Phase 3.3: コア実装 (テストが失敗した後のみ)

GitHub Actionsワークフロー修正

Bashスクリプト修正/新規作成

/releaseコマンド実装

Phase 3.4: 統合 (Integration)

ドキュメント更新

Phase 3.5: 仕上げ (Polish)

既存PR移行

テスト検証

最終確認

依存関係

並列実行例

注意事項

タスク生成ルール

検証チェックリスト

TDD

Research

Phase 0: リサーチ＆技術調査

概要

1. GitHub Actions ブランチフィルタリング

調査内容

調査結果

決定事項

2. semantic-release ブランチ設定

調査内容

調査結果

決定事項

3. gh CLI PR操作

調査内容

調査結果

決定事項

4. Claudeスラッシュコマンド実装

調査内容

調査結果

説明

実行手順

フォーマット: `[ID] [P?] 説明`