spec-runner 1.0.7 → 1.0.9

package/templates/.spec-runner/steps//345/210/206/346/236/220.md

@@ -1,167 +1,105 @@
+---
+step_id: analyze
+phase: null
+readonly: true
+note: 任意フェーズで実行可能（読み取り専用）
+---
+
+# 分析（品質フロー）
 
-> **分析**（品質フロー）文書間の一貫性・矛盾・カバレッジを分析し、読み取り専用でレポートを出力します。
+**やること**: 任意フェーズで、**読み取り専用**で UC 仕様・憲章の一貫性・矛盾・カバレッジを分析し、構造化レポートを出力する（ファイルは変更しない）。
+
+| 項目 | 内容 |
+|------|------|
+| **対象** | UC 仕様（## 実装方針・## タスク含む）、`docs/01_憲章/憲章.md` |
+| **憲章** | **非交渉**。憲章矛盾は **CRITICAL**。原則の無視・勝手な解釈変更は禁止。原則変更は憲章更新手続きで |
 
 ## ユーザー入力
 
+`$ARGUMENTS`（空でなければ必ず考慮）。文末「文脈」にも。
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
-
-## 目的
-
-実装前に、**UC 仕様書**（一番下の ## 実装方針・## タスクを含む）の不整合・重複・曖昧さ・不足を特定する。UC 仕様書と憲章を対象に分析する。
-
-## 制約
-
-**読み取り専用**: ファイルを変更しない。構造化された分析レポートを出力し、必要に応じて修正案を提示する（編集はユーザーが明示的に承認した場合のみ手動で実行）。
-
-**憲章の優先**: プロジェクト憲章（`docs/01_憲章/憲章.md`）は分析範囲内で**非交渉**。憲章との矛盾は自動的に CRITICAL とし、仕様・計画・タスクの修正を求める（原則の解釈変更や無視は禁止）。原則自体の変更は、別途の憲章更新手続きで行う。
-
-## 実行手順
-
-### 1. 分析コンテキストの初期化
-
-リポジトリルートから `.spec-runner/scripts/lib/uc-context.sh --json` を 1 回実行する。現在ブランチは feature/UC-NNN-xxx。JSON から絶対パスを導出する:
-
-- SPEC = FEATURE_SPEC（UC 仕様書。**必須**）
-実装方針・タスクは UC 仕様書（FEATURE_SPEC）の「## 実装方針」「## タスク」に記載されている。
-
-FEATURE_SPEC が無ければエラーで中止。UC 仕様書の一番下に実装方針・タスクの見出しがあることが健全性確認で検証される。
-引数にシングルクォートを含む場合はエスケープ（例: 'I'\''m Groot'）またはダブルクォートを使う。
-
-### 2. 成果物の読み込み（段階的開示）
-
-各成果物から必要最小限の文脈だけを読み込む:
+## 実行フロー
 
-**UC 仕様書（FEATURE_SPEC）から:**
-- 概要/コンテキスト
-- 機能要件
-- 非機能要件
-- ユーザーストーリー
-- エッジケース（あれば）
+### 1. コンテキスト初期化
 
-**UC の「## 実装方針」から:**
-- アーキテクチャ/スタックの選択、データモデル参照、フェーズ、技術的制約
+`.spec-runner/spec-runner.sh 次のステップ --json` を 1 回。`feature/UC-N-xxx`。  
+**SPEC** = FEATURE_SPEC（**必須**）。実装方針・タスクは UC の「## 実装方針」「## タスク」。  
+無ければエラー中止。引数のシングルクォートはエスケープ。
 
-**UC の「## タスク」から:**
-- タスク ID、説明、フェーズ分け、並列マーカー [P]、参照ファイルパス
+### 2. 段階的読み込み
 
-**UC 仕様書に「## 実装方針」がある場合**: そこから技術・実装メモも読み、憲章・仕様との整合を確認する。
+| ソース | 読む範囲 |
+|--------|----------|
+| UC 仕様 | 概要、機能/非機能要件、ユーザーストーリー、エッジケース |
+| ## 実装方針 | アーキテクチャ、データ参照、フェーズ、技術制約 |
+| ## タスク | タスク ID、説明、フェーズ、[P]、参照パス |
+| 憲章 | 原則検証用に全文 |
 
-**憲章から:**
-- `docs/01_憲章/憲章.md` を原則検証用に読み込む
+### 3. 内部モデル（出力に生データを含めない）
 
-### 3. 意味モデルの構築
+- 要件一覧（安定キー付与）
+- ユーザーストーリー/アクション一覧
+- タスク→要件/ストーリーのマッピング
+- 憲章ルールセット（MUST/SHOULD）
 
-内部表現を作成する（生の成果物は出力に含めない）:
+### 4. 検出パス（所見は合計 **50 件まで**、残りはオーバーフロー要約）
 
-- **要件一覧**: 機能・非機能の各要件に安定したキー（例: 「ユーザーがファイルをアップロードできる」→ `user-can-upload-file`）を付与
-- **ユーザーストーリー/アクション一覧**: 受入基準付きの個別ユーザーアクション
-- **タスクカバレッジマッピング**: 各タスクを 1 つ以上の要件またはストーリーに対応づける（キーワード・ID・キーフレーズによる推論）
-- **憲章ルールセット**: 原則名と MUST/SHOULD の規範文を抽出
+| ID | 内容 |
+|----|------|
+| A | 重複（ほぼ同一要件、統合候補） |
+| B | 曖昧さ（測定なし形容詞、TODO/TKTK/???/placeholder） |
+| C | 仕様不足（動詞のみ、受入なしストーリー、未定義ファイル参照タスク） |
+| D | 憲章整合（MUST 違反、ゲート欠落） |
+| E | カバレッジ（要件にタスク 0、孤児タスク、非機能のタスク漏れ） |
+| F | 不整合（用語ずれ、エンティティの有無矛盾、タスク順序矛盾、要件矛盾） |
 
-### 4. 検出パス（トークン効率を意識した分析）
+### 5. 重要度
 
-高シグナルの所見に集中。所見は合計 50 件までとし、残りはオーバーフロー概要に集約する。
+| レベル | 目安 |
+|--------|------|
+| CRITICAL | 憲章 MUST 違反、コア成果物欠落、基本機能を阻害するカバレッジゼロ |
+| HIGH | 重複・矛盾要件、曖昧なセキュリティ/性能、テスト不可能な受入 |
+| MEDIUM | 用語ずれ、非機能のタスク不足、エッジ仕様不足 |
+| LOW | 文体、軽微な重複 |
 
-#### A. 重複検出
-- ほぼ同一の要件を特定
-- 統合のため品質の低い表現に印を付ける
-
-#### B. 曖昧さ検出
-- 測定基準のない曖昧な形容詞（速い・スケーラブル・安全・直感的・堅牢）にフラグ
-- 未解決のプレースホルダ（TODO, TKTK, ???, `<placeholder>` 等）にフラグ
-
-#### C. 仕様不足
-- 動詞はあるが対象や測定可能な結果がない要件
-- 受入基準との対応がないユーザーストーリー
-- 仕様/計画で定義されていないファイル・コンポーネントを参照するタスク
-
-#### D. 憲章との整合
-- MUST 原則に反する要件や計画要素
-- 憲章で求められているセクションや品質ゲートの欠落
-
-#### E. カバレッジギャップ
-- 対応タスクが 0 の要件
-- 対応する要件/ストーリーがないタスク
-- タスクに反映されていない非機能要件（性能・セキュリティなど）
-
-#### F. 不整合
-- 用語のずれ（同一概念がファイル間で異なる名前）
-- 計画では参照されているが仕様にないデータエンティティ（または逆）
-- タスク順序の矛盾（例: 基盤セットアップより前に統合タスクがあり、依存の注記がない）
-- 矛盾する要件（例: 一方は Next.js、他方は Vue を指定）
-
-### 5. 重要度の付与
-
-所見の優先付けに次のヒューリスティックを使う:
-
-- **CRITICAL**: 憲章の MUST 違反、コア仕様成果物の欠落、基本機能を阻害するカバレッジゼロの要件
-- **HIGH**: 重複・矛盾する要件、曖昧なセキュリティ/性能属性、テスト不可能な受入基準
-- **MEDIUM**: 用語のずれ、非機能のタスクカバレッジ不足、仕様不足のエッジケース
-- **LOW**: 文体・表現の改善、実行順序に影響しない軽微な重複
-
-### 6. 簡潔な分析レポートの出力
-
-マークダウンでレポートを出力する（ファイルは書かない）。構成:
+### 6. レポート出力（ファイルに書かない）
 
+```markdown
 ## 仕様分析レポート
 
 | ID | カテゴリ | 重要度 | 場所 | 概要 | 推奨対応 |
 |----|----------|--------|------|------|----------|
-| A1 | 重複 | HIGH | spec.md:L120-134 | 類似要件が2件 ... | 表現を統合し明確な方を残す |
-
-（所見ごとに 1 行。ID はカテゴリ頭文字付きの安定 ID。）
-
-**カバレッジ概要表:**
-
-| 要件キー | タスクあり | タスクID | 注記 |
-|----------|------------|----------|------|
+```
 
-**憲章整合性の問題:**（あれば）
+所見 1 行 1 件。ID はカテゴリ頭文字+連番。
 
-**未マッピングのタスク:**（あれば）
+**カバレッジ概要表** | 要件キー | タスクあり | タスクID | 注記 |
 
-**メトリクス:**
-- 要件総数
-- タスク総数
-- カバレッジ %（タスクが 1 本以上ある要件の割合）
-- 曖昧さの件数
-- 重複の件数
-- CRITICAL の件数
+**憲章整合性の問題** / **未マッピングのタスク**（あれば）
 
-### 7. 次のアクションの提示
+**メトリクス**: 要件数、タスク数、カバレッジ%、曖昧さ件数、重複件数、CRITICAL 件数
 
-レポート末尾に簡潔な「次のアクション」ブロックを出力する:
+### 7. 次のアクション
 
-- CRITICAL がある場合: 「実装」の前に解消するよう推奨する
-- LOW/MEDIUM のみの場合: 改善案を提示したうえで進行可
-- 次のコマンドを明示: 例「仕様策定を修正して再実行」「実装方針を UC の .md に追記」「実装計画でアーキテクチャを調整」
+- CRITICAL あり → 「実装」の前に解消推奨
+- LOW/MEDIUM のみ → 改善案のうえ進行可
+- 次コマンドを明示（仕様修正・実装方針追記・実装計画調整等）
 
-### 8. 修正案の提示
+### 8. 修正案オファー
 
-ユーザーに「上位 N 件について具体的な修正案を出しましょうか？」と尋ねる（自動では適用しない）。
+「上位 N 件について具体的な修正案を出しましょうか？」と尋ねる（自動適用しない）。
 
 ## 運用原則
 
-### コンテキスト効率
-- **最小限の高シグナルトークン**: 実行可能な所見に集中し、網羅的な文書化はしない
-- **段階的開示**: 成果物を少しずつ読み込み、全内容を分析に流し込まない
-- **トークン効率**: 所見表は 50 行まで、オーバーフローは要約
-- **再現性**: 変更なしで再実行すると、同じ ID と件数になる
-
-### 分析ガイドライン
-- **ファイルを変更しない**（読み取り専用）
-- **存在しないセクションを捏造しない**（ない場合はその旨報告）
-- **憲章違反を最優先**（常に CRITICAL）
-- **ルールより具体例**（汎用パターンではなく実例を引用）
-- **所見ゼロのときも丁寧に**（カバレッジ統計付きの成功レポートを出す）
+- 高シグナル・最小トークン、段階的開示、所見表 50 行、再実行で同じ ID・件数
 
 ## 文脈
 
-$ARGUMENTS
+`$ARGUMENTS`
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。

package/templates/.spec-runner/steps//345/256/237/350/243/205.md

@@ -1,91 +1,79 @@
+---
+step_id: implement
+phase: 6
+---
+
+# 実装（Phase 6: IMPLEMENTATION）
 
-> **Phase 6: IMPLEMENTATION（実装）**Phase 5（テスト設計）で作成した PENDING テストをグリーンにする実装を行います。**「完了」はコードが揃っただけでは不十分**。起動確認（dev で `/` と主要画面が応答すること）と、可能なら E2E 1 本グリーンを必須・推奨とする。Phase 5 のレビュー通過（phase-locks 更新）後は、AGENTS.md / CLAUDE.md の更新を検討してください。
+**やること**: Phase 5 の **PENDING テストをグリーン**にする。**完了**はコードだけでなく **起動確認**（dev で `/` と主要画面）と **可能なら E2E 1 本グリーン**。Phase 5 レビュー後は AGENTS.md / CLAUDE.md の更新を検討。
 
-## フォルダ構造ルール
+| 項目 | 内容 |
+|------|------|
+| **UC 配置** | カテゴリ内 **UC-N-xxx.md 1 本**。**## 実装方針**・**## タスク**（または **## タスク一覧**）は **一番下** |
+| **検証** | 完了は check.sh。テストは **`require-tests-green.sh`**（`project.json` の `test_command.run`）が **exit 0** まで「完了」報告しない |
 
-- **docs/** はリポジトリルート直下にのみ置く（設計書は TOP に集約）。
-- **アプリケーションコード**（domain / infrastructure / application / app）は **src/** の下に配置する。docs と同階層に domain や infra を置かない。
-- 例: `src/domain/`, `src/infrastructure/`, `src/application/`, `src/app/`。`tsconfig.json` の `paths` は `"@/*": ["./src/*"]` とする。
+## フォルダ構造
+
+| 種別 | ルール |
+|------|--------|
+| docs | リポジトリルート直下のみ |
+| アプリコード | **src/** 下（domain / infrastructure / application / app）。docs 隣に domain を置かない |
+| paths 例 | `"@/*": ["./src/*"]` |
 
 ## ユーザー入力
 
+`$ARGUMENTS`（空でなければ必ず考慮）
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
-
-## 実行前チェック
-
-**拡張フック（実装前）**:
-- プロジェクトルートに `.spec-runner/extensions.yml` があるか確認する（任意。なければスキップ）
-- あれば `hooks.before_implement` のエントリを読む。YAML が不正なら静かにスキップ
-- `enabled: true` のフックのみ。`condition` の解釈・評価は行わない
-- 任意フック: 拡張名・コマンド・説明・プロンプトを表示。必須フック: コマンドを実行し結果を待ってから概要に進む
-- フックがなければ静かにスキップする
-
-## 概要
-
-1. リポジトリルートから `.spec-runner/scripts/lib/uc-context.sh --json` を実行する。現在ブランチは feature/UC-NNN-xxx。JSON から FEATURE_DIR（カテゴリフォルダ）、FEATURE_SPEC をパースする。**カテゴリ内には UC-NNN-xxx.md を 1 本置く。実装方針・タスクは UC 仕様書の一番下（## 実装方針、## タスク）に記載する。**
-
-2. **チェックリストの状態確認**（FEATURE_DIR/checklists/ が存在する場合のみ）:
-   - checklists/ 内の全ファイルをスキャンする
-   - 各チェックリストで、`- [ ]` / `- [X]` / `- [x]` にマッチする行から総数・完了数・未完了数を数える
-   - 状態表を作成する（チェックリスト名 | 総数 | 完了 | 未完了 | 状態）
-   - **全チェックリストで未完了 0 → PASS**、そうでなければ **FAIL**
-   - **未完了がある場合**: 表を表示し「チェックリストに未完了があります。このまま実装を進めますか？（yes/no）」で停止し、ユーザー応答を待つ。no/待つ/ストップなら停止。yes/進める/続行ならステップ 3 へ
-   - **すべて完了している場合**: 表で全 PASS を表示し、自動でステップ 3 へ
-
-3. **実装文脈の読み込みと分析**:
-   - **必須**: FEATURE_SPEC（UC 仕様書）。ここから受入条件・フロー・成果物を読み取る。
-   - **実装方針・タスクは UC の .md の一番下に書く**: 「## 実装方針」「## タスク」（または「## タスク一覧」）の見出しで記載する。
-
-4. **プロジェクトセットアップの確認**:
-   - **テストコマンド**: `.spec-runner/project.json` の `test_command.run` が無い、またはプロジェクトに合っていない場合は作成・更新する。「実装完了の必須条件」として実行するコマンドを 1 本で書く（例: `npm test`、`docker compose run --rm app npm test`、`poetry run pytest`）。AI は package.json / pyproject.toml / docker-compose.yml 等から推奨を決めてよい。設定は project.json に集約。
-   - リポジトリが git かは `git rev-parse --git-dir 2>/dev/null` で判定。git なら .gitignore を確認・作成する
-   - Dockerfile* または UC の「## 実装方針」に Docker の記述があれば .dockerignore、.eslintrc* があれば .eslintignore、eslint.config.* なら `ignores` を確認、.prettierrc* なら .prettierignore、.npmrc や package.json があれば（公開する場合） .npmignore、*.tf があれば .terraformignore、Helm があれば .helmignore を確認・作成する
-   - 既存の ignore ファイルには必須パターンが含まれているか確認し、不足している重要なパターンのみ追加する。存在しない場合は検出した技術に合わせたパターン一式で作成する
-   - **技術別の共通パターン**: UC 仕様書の「## 実装方針」から技術スタックを読む。無ければプロジェクトの package.json / pyproject.toml 等から判定。Node/TS は node_modules/, dist/, .env*。Python は __pycache__/, .venv/。その他も同様。
-   - **ツール別**: Docker・ESLint・Prettier・Terraform・Kubernetes 等の一般的な除外パターンを追加する
-
-5. **実装すべき内容の整理**: UC 仕様書の「## タスク」または「## タスク一覧」からタスクを解析。受入条件・基本フロー・代替フローと合わせて実装すべき項目を列挙する。
-
-6. **実装の実行**:
-   - UC の「## タスク」に従い、タスクの順序で実行する。
-   - **UC のみの場合**: 仕様書の受入条件・フローに沿って実装する。テスト → コア実装 → 統合の順を推奨。
-   - 同一ファイルを触る作業は順次実行。各単位完了を確認してから次に進む。
-
-7. **実装のルール**:
-   - まずセットアップ: プロジェクト構造・依存・設定の初期化
-   - コードより先にテスト: 契約・エンティティ・統合シナリオのテストを書く場合は先に実行
-   - コア開発: モデル・サービス・CLI コマンド・エンドポイントの実装
-   - 統合: DB 接続・ミドルウェア・ログ・外部サービス
-   - 仕上げと検証: ユニットテスト・性能最適化・ドキュメント
-
-8. **進捗とエラー処理**:
-   - タスク完了ごとに進捗を報告する
-   - 非並列タスクが失敗したら実行を停止する
-   - [P] タスクは成功したものは続行し、失敗したものを報告する
-   - デバッグに役立つ文脈付きの明確なエラーメッセージを出し、続行できない場合は次のステップを提案する
-   - UC の「## タスク」内で完了した項目は [x] にマークする。進捗を簡潔に報告する。
-
-9. **完了検証**:
-   - 必須タスクがすべて完了していることを確認する
-   - 実装した機能が元の仕様と一致していることを確認する
-   - **テストグリーン（必須・強制）**: 完了を報告する前に、必ず **`.spec-runner/scripts/test/require-tests-green.sh`** を実行する。このスクリプトは **`.spec-runner/project.json` の `test_command.run`**（未設定時は package.json / pyproject.toml 等から検出）を実行し、1 件でも失敗すると終了コード 1 を返す。**終了コードが 0 でない場合は「実装完了」とみなさず**、テストを修正してから再度スクリプトを実行する。0 を返すまで完了報告をしてはならない。Docker や Python などは **初期化**（init-project.sh）で `project.json` の `test_command.run` を設定する。
-   - 技術計画に従っていることを確認する
-   - **起動確認（必須）**: アプリが実際に動くことを確認する。
-     - プロジェクトの dev コマンド（例: `npm run dev`）で起動し、ルート（`/`）および当該 UC の主要画面（例: `/dashboard`、該当 API）が 200 または期待どおり応答することを確認する。
-     - 必要なら `.env.example` を `.env` にコピーし DATABASE_URL 等を設定する。README や .env.example に「起動前に .env を作成すること」を記載する。
-     - 起動できない・404 や 500 が返る場合は「完了」とせず、設定・ルーティング・環境を修正してから再度確認する。
-   - **E2E（推奨）**: `tests/e2e/` に当該 UC の E2E がある場合、少なくとも 1 本（ハッピーパス）をグリーンにしてから「実装完了」とする。DB とアプリ起動が必要な場合は手動で実行して確認する。E2E が未作成の場合はユニットテストと起動確認で完了可。
-   - 完了した作業の概要とともに最終状態を報告する
-
-注意: **実装方針・タスクは UC 仕様書の一番下に必須で記載する**（## 実装方針、## タスク）。完了は健全性確認（check.sh）で検証される。
-
-10. **拡張フック（完了検証後）**: `.spec-runner/extensions.yml` の `hooks.after_implement` があれば確認する（なければスキップ）。上記と同様のルールで任意/必須フックを表示または実行する。
+## 実行前チェック: hooks.before_implement
 
----
-完了したら次のステップに進む。
+- `extensions.yml` の `hooks.before_implement`（無ければスキップ、YAML 不正もスキップ）
+- `enabled: true` のみ。condition は評価しない
+- 任意: 表示のみ。必須: 実行して待つ
+
+## 実行フロー
+
+1. **JSON**  
+   `次のステップ --json`。`feature_dir`・`feature_spec`。`feature/UC-N-xxx`。
+
+2. **チェックリスト（FEATURE_DIR/checklists/ がある場合）**  
+   `- [ ]` / `- [x]` を数え表化。未完了 0 → PASS。未完了あり → 「このまま進めますか？ yes/no」で待つ。no で停止。yes で続行。
+
+3. **読込**  
+   FEATURE_SPEC **必須**。実装方針・タスクは UC 一番下。
 
-**次の UC を開始する場合**: `.spec-runner/scripts/branch/uc-next-start.sh` を実行すると、main に切り替えて次の UC 用ブランチ（例: feature/UC-002-xxx）を作成できる。「実行してよろしいですか？」と確認してから実行する。`--yes` を付けると確認なしで実行。実行後は次のステップに進む旨を案内する。
+4. **プロジェクトセットアップ確認**
+   - **test_command.run** が無い/不適なら `project.json` を更新（1 本のコマンド）
+   - git なら .gitignore。Docker/ESLint/Prettier/Terraform/Helm 等に応じ ignore を確認・不足のみ追加
+   - 技術スタックは実装方針または package.json 等から
+
+5. **実装範囲**  
+   ## タスク と受入・フローから項目列挙。
+
+6. **実行**  
+   タスク順。UC のみなら受入・フローに沿い **テスト→コア→統合** 推奨。同一ファイルは順次。
+
+7. **ルールの目安**  
+   セットアップ →（必要なら）テスト先行 → モデル・サービス・EP → 統合 → 仕上げ
+
+8. **進捗・エラー**  
+   タスクごと報告。非並列失敗で停止。[P] は成功分続行。UC タスクの完了は `[x]`。
+
+9. **完了検証**
+   - 必須タスク完了・仕様一致
+   - **`require-tests-green.sh`** が 0 になるまで完了報告禁止
+   - **起動確認（必須）**: dev で `/` と当該 UC の主要画面が 200 等。不可なら修正まで
+   - **E2E（推奨）**: `tests/e2e/` に該当 UC があればハッピーパス 1 本グリーンを目標。無ければユニット+起動で可
+
+10. **hooks.after_implement**  
+    あれば同様に表示/実行。
+
+## 次の UC
+
+`.spec-runner/scripts/branch/uc-next-start.sh` — 実行前に確認。`--yes` で確認省略。main に切り替えて次ブランチ作成。
+
+---
+**次**: 完了後、次のステップへ。次 UC は上記スクリプト。

package/templates/.spec-runner/steps//345/256/237/350/243/205/350/250/210/347/224/273.md

@@ -1,60 +1,72 @@
-> **Phase 2（アーキテクチャ）** および **Phase 4（インフラ詳細設計・Grade A）****docs/05 はカテゴリフォルダ内に UC-NNN-xxx.md を 1 本ずつ置く構成。** 実装方針・タスクは UC の .md の一番下に記載する。Grade A の場合は docs/04_インフラ設計 の成果物も対象にします。
-> **動的設定**: 必須ドキュメント・命名規則は `.spec-runner/project.json` で上書き可能。**初期化**（init-project.sh）で対話的に設定できる。
-
-## フォルダの作成
+---
+step_id: implementation_plan
+phase: "2,4"
+note: アーキテクチャ + Grade A インフラ
+---
 
-- **Phase 2（アーキテクチャ）**: **`docs/03_アーキテクチャ/`** が存在しない場合、このフェーズで新規作成し、パターン選定・インフラ方針・命名規則・設計判断記録（ファイル名は `MMDD-題名.md`。例: `0314-アーキテクチャ選定.md`。年はフォルダ分けで対応可）などの成果物を配置する。spec-runner はフェーズごとにフォルダを1つずつ作っていく流れを想定している。
-- **Phase 4（Grade A・インフラ詳細設計）**: **`docs/04_インフラ設計/`** が存在しない場合、このフェーズで新規作成し、クラウド構成・ネットワーク・**schema.dbml**（DB 構造の単一ソース）等を配置する。ルートの **`migrations/`** は Atlas を使う場合のみ必要に応じて作成する（必須ではない）。
-- **API を公開する場合**: **`docs/06_API仕様/`** が存在しない場合、このフェーズ（または API 仕様を初めて書くフェーズ）で新規作成し、openapi.yaml を配置する。Gate 3 で参照される。
+# 実装計画（Phase 2 アーキテクチャ / Phase 4 インフラ Grade A）
 
-## API 仕様（openapi.yaml）と型・クライアント生成
+**やること**: Phase 2 では `docs/04_アーキテクチャ/` に設計を置く。Phase 4（Grade A）または UC ブランチでは **実装方針を UC の .md の一番下（## 実装方針）** に書き、計画ワークフローを回す。
 
-- **単一ソース**: `docs/06_API仕様/openapi.yaml` が API の正。実装はここから生成した型・クライアントを継承すると設計と一致する。パスは `tags`（例: tasks, task-lists）で分類。必要なら後から `$ref` でファイル分割可。
-- **型・クライアント生成**: `.spec-runner/scripts/openapi/openapi-generate.sh` で行う。プリセットはなく、対話で `.spec-runner/openapi-generator-targets.json` に「名前 → generator・出力先」を追加していく。
-  - 引数なし: 対話（登録済みから選択 or「n」で新規追加。新規は generator 名・出力先を入力 → 生成 → 名前を付けて JSON に保存）。
-  - ターゲット名（例: `typescript`）: 登録した名前で生成。
-  - `--generator <名> --output <dir>`: その場で生成。終了時に「この組み合わせを保存する？名前:」と聞かれたら名前を入れると JSON に追加される。
-  - `--list`: 登録済みターゲット一覧。Generator 一覧: https://openapi-generator.tech/docs/generators/
+| 項目 | 内容 |
+|------|------|
+| **docs/02** | カテゴリフォルダ内に **UC-N-xxx.md を 1 本ずつ**。実装方針・タスクは **各 UC .md の一番下** |
+| **動的設定** | 必須ドキュメント・命名規則は **`.spec-runner/project.json` を AI が直接編集** |
+| **Phase 4 Grade A** | `docs/05_インフラ設計`（schema.dbml 等）も対象。`migrations/` は Atlas 利用時のみ任意 |
 
 ## ユーザー入力
 
+`$ARGUMENTS`（空でなければ必ず考慮）
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
+## フォルダの作成
 
-## 概要
+| フェーズ | パス | 内容の例 |
+|----------|------|----------|
+| Phase 2 | `docs/04_アーキテクチャ/` | パターン選定・インフラ方針・命名・設計判断（`MMDD-題名.md`。年はフォルダ分け可） |
+| Phase 4（Grade A） | `docs/05_インフラ設計/` | クラウド・ネットワーク・**schema.dbml**（DB の単一ソース） |
+| API 公開時 | `docs/06_API仕様/` | openapi.yaml（Gate 3 で参照） |
 
-**Phase 2（アーキテクチャ）で main/develop にいる場合**: UC ブランチにいないため `uc-context.sh` は使わない。`docs/01_憲章/憲章.md` と `docs/02_ドメイン設計/` を読み、**`docs/03_アーキテクチャ/`** にパターン選定・インフラ方針・命名規則・設計判断記録（ファイル名は `MMDD-題名.md`。例: `0314-アーキテクチャ選定.md`。年はフォルダ分けで対応可）を作成する。上記「フォルダの作成」に従い、フォルダが無ければこのフェーズで作成する。
+## API 仕様（openapi.yaml）
 
-**Phase 4（インフラ詳細設計）または UC ブランチ上で実装計画を扱う場合**: **実装方針は UC の .md の一番下（## 実装方針）に書く。** 以下 1–4 を実行する。
+- **単一ソース**: `docs/06_API仕様/openapi.yaml`。型・クライアントはここから生成すると設計と一致。`tags` で分類、`$ref` 分割可。
+- **生成手段**: プロジェクト標準（openapi-generator / openapi-typescript / orval 等）。spec-runner は固定しない。
 
-1. **セットアップ**: リポジトリルートから `.spec-runner/scripts/lib/uc-context.sh --json` を実行し、JSON から FEATURE_SPEC, FEATURE_DIR をパースする。現在ブランチは feature/UC-NNN-xxx であること。引数にシングルクォートを含む場合はエスケープ（例: 'I'\''m Groot'）またはダブルクォートを使う。
+## Phase 2（main/develop、UC ブランチにいない場合）
 
-2. **文脈の読み込み**: FEATURE_SPEC（UC 仕様書。**必須**）と `docs/01_憲章/憲章.md` を読む。UC の .md の「## 実装方針」から技術・実装メモを読む。UC 1 本で計画を立てる。
+`docs/01_憲章/憲章.md` と `docs/03_ドメイン設計/` を読み、**`docs/04_アーキテクチャ/`** にパターン選定・インフラ方針・命名・設計判断記録を作成。フォルダが無ければこのフェーズで作成。
 
-3. **計画ワークフローの実行**: UC 仕様書（と実装方針セクション）に従い、以下を行う:
-   - 技術コンテキストを埋める（不明点は "要確認" とマーク）
-   - 憲章から憲章チェックセクションを埋める
-   - ゲートを評価する（違反が正当化されない場合は ERROR）
-   - **ファイル構成**: docs はルート直下。アプリケーションコード（app / domain / application / infrastructure）は **src/** に配置する（憲章・アーキテクチャで既に決まっていればそのまま）。
-   - Phase 0: research.md は任意（要確認がある場合のみ）。
-   - Phase 1: **data-model.md / contracts/ は任意**。データモデルは 集約.md と schema.dbml・コードで正とする。API 契約は openapi.yaml でよい。必要なら FEATURE_DIR に data-model.md / contracts/ を追加してよい。
-   - 設計後に憲章チェックを再評価する
+## Phase 4 または UC 上での計画（実装方針セクション）
 
-4. **停止と報告**: コマンドは Phase 2 計画の後で終了する。ブランチ、FEATURE_SPEC、生成した成果物を報告する。
+以下 1–4 を実行。
 
-## フェーズ
+1. **セットアップ**  
+   `.spec-runner/spec-runner.sh 次のステップ --json`。`feature_spec`・`feature_dir`。UC ブランチ上であること。
 
-### Phase 0: 概要とリサーチ
+2. **文脈**  
+   FEATURE_SPEC（**必須**）、`docs/01_憲章/憲章.md`、UC の「## 実装方針」。UC 1 本で計画。
 
-1. **技術コンテキストから不明点を抽出**:
-   - 各「要確認」→ リサーチタスク
-   - 各依存関係 → ベストプラクティスタスク
-   - 各連携 → パターンタスク
+3. **計画ワークフロー**
+   - 技術コンテキスト（不明は「要確認」）
+   - 憲章チェックを憲章から埋める
+   - ゲート評価（正当化されない違反は ERROR）
+   - **ファイル構成**: docs はルート直下。アプリコードは **src/**（憲章・アーキで決まっていれば従う）
+   - Phase 0: research.md は任意（要確認がある場合のみ）
+   - Phase 1: **data-model.md / contracts/ は任意**。正は 集約.md・schema.dbml・コード。API は openapi.yaml。必要なら FEATURE_DIR や docs/04 に追加可
+   - 設計後に憲章チェックを再評価
 
-2. **リサーチエージェントの生成と投入**:
+4. **停止と報告**  
+   コマンドは Phase 2 計画の後で終了。ブランチ・FEATURE_SPEC・生成物を報告。
+
+## サブフェーズ詳細
+
+### Phase 0: 概要とリサーチ
+
+1. 技術コンテキストの「要確認」→ リサーチタスク、依存→ベストプラクティス、連携→パターンタスク
+2. リサーチタスク例:
 
    ```text
    技術コンテキストの各不明点について:
@@ -63,34 +75,22 @@ $ARGUMENTS
      タスク: 「{ドメイン} における {技術} のベストプラクティスを調べる」
    ```
 
-3. **結果を `research.md` に集約**。形式:
-   - 決定: [選んだ内容]
-   - 理由: [選んだ理由]
-   - 検討した代替案: [評価した他の案]
-
-**成果物**: 要確認がすべて解消された research.md
+3. **research.md** に集約: 決定 / 理由 / 検討した代替案  
+   **成果物**: 要確認が解消された research.md
 
 ### Phase 1: 設計と契約
 
-**前提:** research.md が完了していること
-
-1. **機能仕様からエンティティを抽出** → `data-model.md`:
-   - エンティティ名・フィールド・リレーション
-   - 要件からのバリデーションルール
-   - 該当する場合は状態遷移
+**前提**: research.md 完了（使う場合）
 
-2. **インターフェース契約の定義**（プロジェクトに外部インターフェースがある場合）→ `/contracts/`:
-   - ユーザーや他システムに公開するインターフェースを特定する
-   - プロジェクトタイプに合った契約形式で文書化する
-   - 例: ライブラリの公開 API、CLI のコマンドスキーマ、Web サービスのエンドポイント、パーサの文法、アプリの UI 契約
-   -  purely 内部（ビルドスクリプト・単発ツール等）の場合はスキップする
+1. 機能仕様からエンティティ抽出 → `data-model.md`（フィールド・リレ・バリデ・状態遷移）
+2. 外部 IF がある場合 → `/contracts/`（公開 API・CLI・Web 等）。純内部はスキップ可
 
-**成果物**: data-model.md / contracts/ / quickstart.md は**任意**。コードと 集約.md・openapi.yaml で分かる場合は不要。作る場合は FEATURE_DIR 内または docs/04 等に配置してよい。
+**成果物**: data-model / contracts / quickstart は**任意**。コードと 集約.md・openapi で足りなければ作る。
 
 ## 重要ルール
 
 - 絶対パスを使用する
-- ゲート違反や未解消の確認事項がある場合は ERROR とする
+- ゲート違反・未解消の確認事項は ERROR
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。