spec-runner 1.0.7 → 1.0.9

package/templates/.spec-runner/steps/steps.json

@@ -0,0 +1,171 @@
+{
+  "version": 1,
+  "note": "steps/*.md の『宣言（機械可読）』。md は実行テンプレ、こちらはルールと入出力の参照用。",
+  "common": {
+    "docs": {
+      "root": "docs",
+      "charter": "docs/01_憲章/憲章.md",
+      "uc_root": "docs/02_ユースケース仕様",
+      "domain_root": "docs/03_ドメイン設計",
+      "architecture_root": "docs/04_アーキテクチャ",
+      "infra_root": "docs/05_インフラ設計",
+      "api_root": "docs/06_API仕様",
+      "openapi": "docs/06_API仕様/openapi.yaml"
+    },
+    "commands": {
+      "check": ".spec-runner/scripts/check.sh",
+      "start_next_uc": ".spec-runner/scripts/branch/uc-next-start.sh"
+    },
+    "naming": {
+      "uc_id_regex": "^UC-[0-9]+$",
+      "uc_branch_regex": "^(?<prefix>[^/]+)/(?<uc>UC-[0-9]+)-(?<slug>[a-z0-9-]+)$",
+      "uc_spec_regex": "^UC-[0-9]+-.+\\.md$",
+      "decision_log_dir_name": "判断記録",
+      "decision_log_filename_pattern": "UC-N-MMDD-題名.md",
+      "decision_log_example": "UC-1-0317-要件解釈.md"
+    },
+    "clarification_policy": {
+      "marker_format": "[要確認: ...]",
+      "rule": "不明点は推測で確定せず、仕様/設計書内に [要確認: ...] として残す。",
+      "interactive_questions_max": 3,
+      "excess_handling": "質問として提示するのは最大3件。残りは『追加の要確認』として文書内に残す。"
+    },
+    "uc_to_domain_to_arch_flow": {
+      "order": ["charter", "uc_spec", "domain", "architecture"],
+      "note": "憲章の次は UC→ドメイン→アーキ。UC を入力にドメインを固め、ドメインを入力にアーキを固める。"
+    }
+  },
+  "steps": [
+    {
+      "id": "charter",
+      "name_ja": "憲章",
+      "phase": 0,
+      "md_file": "憲章.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/01_憲章/憲章.md"],
+      "notes": ["存在しない場合は .spec-runner/templates/憲章.md から生成する"]
+    },
+    {
+      "id": "uc_spec",
+      "name_ja": "仕様策定",
+      "phase": 1,
+      "md_file": "仕様策定.md",
+      "commands": [
+        { "id": "start_uc_branch", "command": ".spec-runner/scripts/branch/uc-next-start.sh" },
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/02_ユースケース仕様/<カテゴリ>/UC-<N>-<題名>.md"],
+      "secondary_outputs_optional": ["docs/02_ユースケース仕様/<カテゴリ>/判断記録/UC-N-MMDD-題名.md"]
+    },
+    {
+      "id": "domain",
+      "name_ja": "ドメイン設計",
+      "phase": 2,
+      "md_file": "ドメイン設計.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": [
+        "docs/03_ドメイン設計/ユビキタス言語辞書.md",
+        "docs/03_ドメイン設計/ドメインモデル.md",
+        "docs/03_ドメイン設計/集約.md"
+      ],
+      "notes": ["存在しない場合は .spec-runner/templates/ から生成する"]
+    },
+    {
+      "id": "architecture_plan",
+      "name_ja": "実装計画",
+      "phase": 3,
+      "md_file": "実装計画.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/04_アーキテクチャ/*"],
+      "secondary_outputs_optional": ["docs/06_API仕様/openapi.yaml"]
+    },
+    {
+      "id": "infra_plan",
+      "name_ja": "インフラ詳細設計（Grade A）",
+      "phase": 4,
+      "md_file": "実装計画.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/05_インフラ設計/schema.dbml"]
+    },
+    {
+      "id": "test_design",
+      "name_ja": "テスト設計",
+      "phase": 5,
+      "md_file": "テスト設計.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["<test_design.dir>/**/UC-N-*.spec.*"]
+    },
+    {
+      "id": "implement",
+      "name_ja": "実装",
+      "phase": 6,
+      "md_file": "実装.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["src/**", "<tests green>"],
+      "notes": ["完了条件: require-tests-green.sh が exit 0"]
+    },
+    {
+      "id": "clarify",
+      "name_ja": "曖昧さ解消",
+      "phase": null,
+      "md_file": "曖昧さ解消.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/02_ユースケース仕様/<カテゴリ>/UC-<N>-<題名>.md (更新)"]
+    },
+    {
+      "id": "analyze",
+      "name_ja": "分析",
+      "phase": null,
+      "md_file": "分析.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/02_ユースケース仕様/<カテゴリ>/UC-<N>-<題名>.md (更新)"]
+    },
+    {
+      "id": "checklist",
+      "name_ja": "チェックリスト",
+      "phase": 1,
+      "md_file": "チェックリスト.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/02_ユースケース仕様/<カテゴリ>/checklists/*.md (任意)"]
+    },
+    {
+      "id": "task_list",
+      "name_ja": "タスク一覧",
+      "phase": 1,
+      "md_file": "タスク一覧.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["docs/02_ユースケース仕様/<カテゴリ>/UC-<N>-<題名>.md (## タスク / ## タスク一覧 更新)"]
+    },
+    {
+      "id": "other_work",
+      "name_ja": "その他作業",
+      "phase": 1,
+      "md_file": "その他作業.md",
+      "commands": [
+        { "id": "check", "command": ".spec-runner/scripts/check.sh" }
+      ],
+      "primary_outputs": ["(branch scoped)"]
+    }
+  ]
+}
+

package/templates/.spec-runner/steps//343/201/235/343/201/256/344/273/226/344/275/234/346/245/255.md

@@ -1,22 +1,34 @@
-# その他作業（CI/CD・インフラ・共通設定など）
+---
+step_id: other_work
+phase: null
+note: UC ブランチではない
+---
 
-**このブランチは UC 用ではありません。** `feature/<接頭辞>/xxx` 形式（接頭辞は project.json の **naming.other_work_prefixes** で指定）のため、spec-runner は「CI/CD 構築」「インフラ」「共通設定」など UC 以外の作業用とみなします。
+# その他作業（CI/CD・インフラ・共通設定など）
 
-## ブランチの例
+**やること**: UC 以外の作業用ブランチ上で、通常開発フローで進める。spec-runner の UC ステップ（仕様策定〜実装）は**対象外**。
 
-- `feature/cicd/github-actions` … CI/CD 構築
-- `feature/infra/docker` … インフラ・コンテナ
-- `feature/work/setup-tooling` … 共通ツール導入
+| 項目 | 内容 |
+|------|------|
+| **ブランチ** | `feature/<接頭辞>/xxx`（接頭辞は `project.json` の **naming.other_work_prefixes**。既定: work, infra, cicd） |
+| **UC フロー** | このステップのまま **仕様策定〜実装は実行しない** |
+| **参照** | 必要なら `.spec-runner/steps/実装計画.md` と docs/03, 04, 06 等 |
 
-接頭辞は **project.json の naming.other_work_prefixes** に配列で書く（既定: work, infra, cicd）。プロジェクトに合わせて追加・変更してよい。
+## ブランチの例
 
-## やること
+| ブランチ例 | 用途 |
+|------------|------|
+| `feature/cicd/github-actions` | CI/CD |
+| `feature/infra/docker` | インフラ・コンテナ |
+| `feature/work/setup-tooling` | 共通ツール |
 
-- **spec-runner の UC ステップ（仕様策定〜実装）は対象外**。このステップを出したまま、通常の開発フローで進めてよい。
-- 必要に応じて **実装計画.md**（`.spec-runner/steps/実装計画.md`）を参照し、設計書（docs/03, docs/04, docs/06 等）に沿って作業する。
-- 作業が終わったら main にマージするか、UC 用ブランチ（`feature/UC-NNN-xxx`）に切り替えて spec-runner を再実行する。
+接頭辞は **project.json の naming.other_work_prefixes** に配列で記載。プロジェクトに合わせて追加・変更可。
 
 ## 注意
 
-- phase-locks の `uc_reviewed` や UC 用の判定には影響しない。このブランチ用の lock は不要。
-- 再度 spec-runner で「次のステップ」を見たい場合は、UC 用ブランチにチェックアウトするか、main に戻る。
+- phase-locks の `uc_reviewed` や UC 判定には**影響しない**。このブランチ用 lock は不要。
+- 再度「次のステップ」を見たい場合は **UC ブランチに checkout** するか **main に戻る**。
+- 作業完了後は main にマージするか、UC ブランチに切り替えて spec-runner を再実行。
+
+---
+**次**: UC 作業に戻る場合は適切なブランチへ。

package/templates/.spec-runner/steps//343/202/277/343/202/271/343/202/257/344/270/200/350/246/247.md

@@ -1,132 +1,95 @@
-> **実装タスクの整理**: UC 仕様書（UC-NNN-xxx.md）の**一番下**に「## タスク」または「## タスク一覧」セクションを追加・更新する。タスクは UC の .md 内に記載する。テスト設計は別ステップ「テスト設計」で行う。
-
-## ユーザー入力
-
-```text
-$ARGUMENTS
-```
-
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
+---
+step_id: tasks
+phase: planning
+---
 
-## 実行前チェック
+# タスク一覧（実装タスクの整理）
 
-**拡張フックの確認（タスク生成前）**:
-- プロジェクトルートに `.spec-runner/extensions.yml` が存在するか確認する（任意。なければスキップ）
-- あれば `hooks.before_tasks` のエントリを読む
-- YAML がパースできない・不正な場合はフック確認を静かにスキップして続行
-- `enabled: true` のフックだけを対象にする
-- 各フックの `condition` 式の解釈・評価は行わない（条件が空でなければフックをスキップし、評価は HookExecutor に任せる）
-- 実行可能なフックごとに `optional` に応じて出力する:
-  - **任意フック**（`optional: true`）: 拡張名・コマンド・説明・プロンプト・実行方法を表示
-  - **必須フック**（`optional: false`）: 拡張名・実行するコマンドを表示し、結果を待ってから概要に進む
-- 登録フックがなければ、または `.spec-runner/extensions.yml` がなければ静かにスキップする
+**やること**: UC 仕様書の**一番下**に `## タスク` または `## タスク一覧` を追加・更新する。テスト設計は別ステップ。
 
-## 概要
+| 項目 | 内容 |
+|------|------|
+| **検証** | 見出し・形式は **check.sh（健全性確認）** で検証 |
+| **即実行可能性** | 各タスクは LLM が追加文脈なしで完了できる具体性 |
 
-1. **セットアップ**: リポジトリルートから `.spec-runner/scripts/lib/uc-context.sh --json` を実行する。現在ブランチは feature/UC-NNN-xxx。JSON から FEATURE_SPEC（UC 仕様書）、FEATURE_DIR をパースする。パスは絶対パス。引数にシングルクォートを含む場合はエスケープ（例: 'I'\''m Groot'）またはダブルクォートを使う。
+## ユーザー入力
 
-2. **設計ドキュメントの読み込み**: FEATURE_SPEC（UC 仕様書）を必須で読む。UC の「## 実装方針」から技術スタック・構造を読む。無ければ UC 仕様書とプロジェクト既存ファイルから推測する。
+`$ARGUMENTS`（空でなければ必ず考慮）。タスク整理の文脈にも。
 
-3. **タスク整理ワークフローの実行**:
-   - UC の「## 実装方針」から技術スタック・プロジェクト構造を抽出する。無ければ UC 仕様書とプロジェクト既存ファイルから推測する。
-   - spec.md を読み、優先度（P1, P2, P3 等）付きユーザーストーリーを抽出する
-   - data-model.md があればエンティティを抽出しユーザーストーリーにマッピングする
-   - contracts/ があればインターフェース契約をユーザーストーリーにマッピングする
-   - research.md があれば決定をセットアップタスクに反映する
-   - ユーザーストーリーごとにタスクを整理して生成する（下記タスク生成ルール参照）
-   - ユーザーストーリー完了順の依存グラフを作成する
-   - ストーリーごとに並列実行例を作成する
-   - タスクの完全性を検証する（各ユーザーストーリーに必要なタスクが揃い、独立してテスト可能であること）
+```text
+$ARGUMENTS
+```
 
-4. **UC 仕様書へのタスクセクション追加・更新**: **FEATURE_SPEC（UC の .md）の一番下**に「## タスク」または「## タスク一覧」見出しを置き、以下で埋める。既にセクションがあれば内容を更新する。
-   - UC の実装方針から正しい機能名
-   - Phase 1: セットアップタスク（プロジェクト初期化）
-   - Phase 2: 基盤タスク（全ユーザーストーリーの前提）
-   - Phase 3 以降: 優先度順でユーザーストーリーごとに 1 フェーズ
-   - 各フェーズにストーリー目標・独立したテスト基準・（依頼があれば）テスト・実装タスクを含める
-   - 最終フェーズ: 仕上げと横断的関心事
-   - 全タスクは下記チェックリスト形式に厳守する
-   - 各タスクに明確なファイルパスを付ける
-   - ストーリー完了順の依存セクション
-   - ストーリーごとの並列実行例
-   - 実装戦略セクション（MVP 優先・段階的リリース）
+## 実行前チェック: 拡張フック（タスク生成前）
 
-5. **報告**: 更新した UC 仕様書（FEATURE_SPEC）のパスとタスクセクションの概要を出力する:
-   - タスク総数
-   - ユーザーストーリーごとのタスク数
-   - 並列実行の機会
-   - ストーリーごとの独立したテスト基準
-   - 推奨 MVP スコープ（多くはユーザーストーリー 1 のみ）
-   - 形式検証: 全タスクがチェックリスト形式（チェックボックス・ID・ラベル・ファイルパス）に従っていることを確認する
+- `.spec-runner/extensions.yml` の有無（無ければスキップ）
+- `hooks.before_tasks`、YAML 不正は静かにスキップ
+- `enabled: true` のみ。`condition` の評価はせず（HookExecutor に任せる）
+- **optional: true** → 拡張名・コマンド・説明・プロンプト・実行方法を表示
+- **optional: false** → コマンド実行し結果を待ってから続行
+- フック無しはスキップ
 
-6. **拡張フックの確認（タスク追記後）**: UC へのタスクセクション追記後に `.spec-runner/extensions.yml` の `hooks.after_tasks` があれば同様のルールで表示または実行する（なければスキップ）。
+## 実行フロー
 
-タスク整理の文脈: $ARGUMENTS
+1. **セットアップ**  
+   `次のステップ --json`。`FEATURE_SPEC`・`FEATURE_DIR`。
 
-UC 内のタスクセクションは即実行可能であること。各タスクは LLM が追加文脈なしで完了できる程度に具体的であること。**確定事項の完了は健全性確認（check.sh）で検証される。**
+2. **読込**  
+   FEATURE_SPEC **必須**。`## 実装方針` から技術・構造。無ければ仕様と既存ファイルから推測。
 
-## タスク生成ルール
+3. **ワークフロー**  
+   - 実装方針からスタック・構造（無ければ推測）
+   - spec.md から優先度付きユーザーストーリー
+   - data-model / contracts / research があれば反映
+   - ストーリーごとにタスク生成（**付録: 生成ルール**）
+   - 依存グラフ、並列例、完全性検証
 
-**重要**: 独立した実装・テストを可能にするため、タスクは**ユーザーストーリーごと**に整理すること。
+4. **UC への書き込み**  
+   FEATURE_SPEC **一番下**に `## タスク` または `## タスク一覧`。既存なら更新。  
+   Phase 1 セットアップ → Phase 2 基盤 → Phase 3+ ストーリー順 → 最終フェーズ仕上げ。  
+   チェックリスト形式厳守、ファイルパス付き、依存・並列例・実装戦略（MVP 等）。
 
-**テストは任意**: 機能仕様またはユーザーが TDD を依頼した場合にのみ、テストタスクを生成する。
+5. **報告**  
+   パス、タスク総数、ストーリー別件数、並列機会、テスト基準、推奨 MVP、形式検証結果。
 
-### チェックリスト形式（必須）
+6. **タスク追記後**  
+   `hooks.after_tasks` があれば同様に表示/実行。
 
-各タスクは次の形式に厳守する:
+## 付録: チェックリスト形式（必須）
 
 ```text
 - [ ] [TaskID] [P?] [Story?] 説明（ファイルパス付き）
 ```
 
-**構成要素**:
-
-1. **チェックボックス**: 常に `- [ ]` で始める
-2. **タスク ID**: 実行順の連番（T001, T002, T003 ...）
-3. **[P] マーカー**: 並列実行可能なタスクのみ付ける（別ファイル・未完了タスクに依存しない）
-4. **[Story] ラベル**: ユーザーストーリーフェーズのタスクのみ必須。形式: [US1], [US2], [US3] 等（spec.md のユーザーストーリーに対応）。セットアップ・基盤・仕上げフェーズにはストーリーラベルを付けない
-5. **説明**: 明確なアクションと正確なファイルパス
-
-**例**:
-
-- ✅ 正: `- [ ] T001 実装計画に従いプロジェクト構造を作成する`
-- ✅ 正: `- [ ] T005 [P] src/middleware/auth.py に認証ミドルウェアを実装する`
-- ✅ 正: `- [ ] T012 [P] [US1] src/models/user.py に User モデルを作成する`
-- ✅ 正: `- [ ] T014 [US1] src/services/user_service.py に UserService を実装する`
-- ❌ 誤: `- [ ] User モデルを作成する`（ID とストーリーラベルがない）
-- ❌ 誤: `T001 [US1] モデルを作成する`（チェックボックスがない）
-- ❌ 誤: `- [ ] [US1] User モデルを作成する`（タスク ID がない）
-- ❌ 誤: `- [ ] T001 [US1] モデルを作成する`（ファイルパスがない）
-
-### タスクの整理
-
-1. **ユーザーストーリー（spec.md）を主軸とする**:
-   - 各ユーザーストーリー（P1, P2, P3 ...）に 1 フェーズ
-   - ストーリーに関連するコンポーネントをすべてマッピング: モデル・サービス・インターフェース/UI・（依頼があれば）テスト
-   - ストーリー間の依存を記載する（多くのストーリーは独立）
+| 要素 | ルール |
+|------|--------|
+| チェックボックス | 常に `- [ ]` |
+| TaskID | T001, T002, … |
+| [P] | 並列可のみ（別ファイル・未完了に非依存） |
+| [Story] | ストーリーフェーズは [US1] 等。セットアップ・基盤・仕上げには付けない |
+| 説明 | 明確なアクション + **正確なファイルパス** |
 
-2. **契約から**:
-   - 各インターフェース契約を、それを提供するユーザーストーリーに対応づける
-   - テストを依頼されている場合: 各契約に対して、そのストーリーフェーズの実装前に契約テストタスク [P] を置く
+| 例 | 行 |
+|----|-----|
+| ✅ | `- [ ] T001 実装計画に従いプロジェクト構造を作成する` |
+| ✅ | `- [ ] T005 [P] src/middleware/auth.py に認証ミドルウェアを実装する` |
+| ✅ | `- [ ] T012 [P] [US1] src/models/user.py に User モデルを作成する` |
+| ✅ | `- [ ] T014 [US1] src/services/user_service.py に UserService を実装する` |
+| ❌ | User モデルを作成する（ID・ストーリーラベルなし） |
+| ❌ | `T001 [US1] モデルを作成する`（チェックボックスなし） |
+| ❌ | `- [ ] [US1] User モデルを作成する`（タスク ID なし） |
+| ❌ | `- [ ] T001 [US1] モデルを作成する`（ファイルパスなし） |
 
-3. **データモデルから**:
-   - 各エンティティを、それを必要とするユーザーストーリーに対応づける
-   - 複数ストーリーで使うエンティティは、最初のストーリーまたはセットアップフェーズに含める
-   - リレーションは適切なストーリーフェーズのサービス層タスクで扱う
+## 付録: タスク生成ルール
 
-4. **セットアップ/インフラから**:
-   - 共通インフラ → Phase 1（セットアップ）
-   - 基盤/ブロッキングタスク → Phase 2（基盤）
-   - ストーリー固有のセットアップ → そのストーリーのフェーズ内
+- **主軸**: spec.md のユーザーストーリー。ストーリーごと 1 フェーズ、コンポーネントをマッピング
+- **契約**: 提供ストーリーに対応。TDD 依頼時は契約テスト [P] を実装前に
+- **データモデル**: エンティティを必要ストーリーへ。共有は最初のストーリーまたはセットアップ
+- **インフラ**: 共通 → Phase 1、基盤 → Phase 2、ストーリー固有 → そのストーリー内
 
-### フェーズ構成
+**フェーズ**: Phase 1 セットアップ → Phase 2 基盤（全ストーリー前提）→ Phase 3+ P1,P2,…（テスト→モデル→サービス→EP→統合）→ 最終 仕上げ・横断
 
-- **Phase 1**: セットアップ（プロジェクト初期化）
-- **Phase 2**: 基盤（全ユーザーストーリーの前提。ユーザーストーリーより前に完了必須）
-- **Phase 3 以降**: 優先度順のユーザーストーリー（P1, P2, P3 ...）
-  - 各ストーリー内: （依頼があれば）テスト → モデル → サービス → エンドポイント → 統合
-  - 各フェーズは独立してテスト可能な増分として完了させる
-- **最終フェーズ**: 仕上げと横断的関心事
+**テストタスク**: 機能仕様またはユーザーが TDD を依頼した場合のみ。
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。

package/templates/.spec-runner/steps//343/203/201/343/202/247/343/203/203/343/202/257/343/203/252/343/202/271/343/203/210.md

@@ -1,106 +1,80 @@
-> **チェックリスト**（品質フロー）要件品質（完全性・明確性・測定可能性）のチェックリストを生成します。
-
-## 確定事項（必ず守る）
-
-- **実装方針・タスクは UC 仕様書（UC-NNN-xxx.md）の一番下に書く。** `## 実装方針` と `## タスク`（または `## タスク一覧`）の見出しで記載する。1 UC = 1 本の .md。
-- **守られているか**は、健全性確認（`.spec-runner/scripts/check.sh` または `check/health.sh`）で検証する。見出しが無い場合は指摘され、完了とみなされない。
+---
+step_id: checklist
+phase: quality
+---
 
-## チェックリストの目的:「要件のユニットテスト」
+# チェックリスト（品質フロー）
 
-**重要**: チェックリストは**要件を書くことのユニットテスト**である。あるドメインにおける要件の品質・明確さ・完全性を検証する。
+**やること**: **要件品質**（完全性・明確性・測定可能性）のチェックリストを生成する。**実装や UI の動作確認ではない**。
 
-**検証/テスト用ではない**:
-- ❌ 「ボタンが正しくクリックされることを確認する」ではない
-- ❌ 「エラー処理が動くことをテストする」ではない
-- ❌ 「API が 200 を返すことを確認する」ではない
-- ❌ コード/実装が仕様と一致しているかのチェックではない
+| 項目 | 内容 |
+|------|------|
+| **配置** | `## 実装方針` と `## タスク`（または `## タスク一覧`）は **UC-N-xxx.md の一番下**。健全性は `check.sh` で検証 |
+| **比喩** | 仕様が「コード」ならチェックリストはその**ユニットテスト**（要件がよく書かれているか） |
 
-**要件品質の検証用**:
-- ✅ 「全カードタイプで視覚的階層の要件が定義されているか」（完全性）
-- ✅ 「目立つ表示」が具体的なサイズ/位置で定量化されているか（明確さ）
-- ✅ 「ホバー状態の要件が全インタラクティブ要素で一貫しているか」（一貫性）
-- ✅ 「キーボード操作の要件が定義されているか」（カバレッジ）
-- ✅ 「ロゴ画像の読み込み失敗時の挙動が仕様で定義されているか」（エッジケース）
+## 確定事項
 
-**比喩**: 仕様が英語で書かれたコードなら、チェックリストはそのユニットテストスイート。実装が動くかではなく、**要件がよく書かれていて完全・曖昧でなく実装の準備ができているか**をテストする。
+| ✅ チェックリストである | ❌ チェックリストでない |
+|-------------------------|-------------------------|
+| 要件の完全性・明確さ・一貫性・カバレッジを問う | ボタンクリック・API 200・エラー処理の動作確認 |
+| 仕様で「何が定義されているか」を問う | コードが仕様と一致するか |
 
 ## ユーザー入力
 
+`$ARGUMENTS`（空でなければ必ず考慮）
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
-
-## 実行手順
-
-1. **セットアップ**: リポジトリルートから `.spec-runner/scripts/lib/uc-context.sh --json --paths-only` を実行する。現在ブランチは feature/UC-NNN-xxx。JSON から FEATURE_SPEC（UC 仕様書）と FEATURE_DIR（カテゴリフォルダ。docs/05_ユースケース仕様/<カテゴリ>/）をパースする。パスは絶対パス。引数にシングルクォートを含む場合はエスケープ（例: 'I'\''m Groot'）またはダブルクォートを使う。
-
-2. **意図の明確化（動的）**: 事前のカタログではなく、ユーザーの表現と spec/plan/tasks から抽出したシグナルに基づき、最大 3 つの文脈的な確認質問を生成する。次の条件を満たすこと:
-   - 回答がチェックリストの内容を実質的に変える情報だけを聞く
-   - `$ARGUMENTS` で既に明確な質問は個別にスキップする
-   - 広さより精度を優先する
-   - 質問は Q1/Q2/Q3 で表示。回答後、代替/例外/復旧/非機能など 2 クラス以上が未明確なら、最大 2 問のフォローアップ（Q4/Q5）を 1 行の理由付きで出してよい。合計 5 問を超えない。ユーザーがこれ以上不要と言ったら増やさない。
-
-3. **ユーザー要求の把握**: `$ARGUMENTS` と確認回答を合わせ、チェックリストのテーマ（例: セキュリティ・レビュー・デプロイ・UX）・必須項目・カテゴリの骨子を決める。spec/plan/tasks から不足文脈を推測する（捏造しない）。
-
-4. **機能文脈の読み込み**: FEATURE_SPEC（UC 仕様書）を必須で読む。実装方針・タスクは **UC の .md の一番下**（## 実装方針、## タスク）に書かれている。**checklists は任意**。UC のみで進める場合はチェックリストを生成しない選択も可。
-
-5. **チェックリストの生成（任意）— 「要件のユニットテスト」を作る**:
-   - チェックリストを用意する場合のみ: `FEATURE_DIR/checklists/` がなければ作成する
-   - ドメインに基づく短い説明的なファイル名（例: `ux.md`, `api.md`, `security.md`）で一意のファイルを生成する
-   - ファイルが存在しなければ新規作成し CHK001 から番号を振る。存在すれば既存内容を残し、最後の CHK ID の続きから追記する（例: 最後が CHK015 なら CHK016 から）。既存のチェックリスト内容は削除・上書きせず、常に追記する
-
-   **原則 — 実装ではなく要件をテストする**  
-   各項目は**要件そのもの**について次を評価する:
-   - **完全性**: 必要な要件がすべてあるか
-   - **明確さ**: 要件が曖昧でなく具体的か
-   - **一貫性**: 要件同士が矛盾していないか
-   - **測定可能性**: 客観的に検証できるか
-   - **カバレッジ**: シナリオ/エッジケースが網羅されているか
-
-   **カテゴリ**: 要件品質の観点でグループ化する（要件の完全性・明確さ・一貫性・受入基準の品質・シナリオカバレッジ・エッジケース・非機能要件・依存と仮定・曖昧さと矛盾）。
-
-   **項目の書き方**:
-   - ❌ 誤: 「ランディングに 3 枚のカードが表示されることを確認する」「ホバーがデスクトップで動くことをテストする」→ 実装のテストになっている
-   - ✅ 正: 「 featured の枚数とレイアウトが仕様で明示されているか」「目立つ表示が具体的なサイズ/位置で定量化されているか」「ホバー状態の要件が全インタラクティブ要素で一貫しているか」
-
-   **項目構造**: 質問形式で要件品質を聞く。仕様/計画に**書かれている（いない）**ことに焦点。品質次元を [完全性/明確さ/一貫性/等] の括弧で付ける。既存要件の確認時は `[Spec §X.Y]`、不足の確認時は `[Gap]` を使う。
-
-   **禁止**: 「Verify」「Test」「Confirm」「Check」+ 実装の挙動で始める項目、コード実行・ユーザー操作・システム挙動への言及、「正しく表示される」「正しく動作する」、テストケース/テスト計画/QA 手順、実装詳細（フレームワーク・API・アルゴリズム）は**禁止**。
+## 実行フロー
 
-   **推奨パターン**: 「[要件タイプ] が [シナリオ] で定義/仕様化/文書化されているか」「[曖昧な語] が具体的な基準で定量化/明確化されているか」「[セクション A] と [セクション B] で要件が一貫しているか」「[要件] を客観的に測定/検証できるか」「[エッジケース/シナリオ] が要件で扱われているか」「仕様に [不足している観点] が定義されているか」。
+1. **セットアップ**  
+   `次のステップ --json`。`FEATURE_SPEC`・`FEATURE_DIR`（`docs/02_.../<カテゴリ>/`）。
 
-   **トレーサビリティ**: 項目の 80% 以上に、仕様セクション `[Spec §X.Y]` または `[Gap]` / `[曖昧さ]` / `[矛盾]` / `[仮定]` のいずれかを含める。
+2. **動的な意図確認（最大 3 問 + フォローアップ最大 2）**  
+   spec/plan/tasks からシグナル抽出。`$ARGUMENTS` で明確ならスキップ。Q1–Q3。2 クラス以上未明確なら Q4–Q5（合計 5 問上限）。ユーザーが不要なら増やさない。
 
-   **統合**: 候補が 40 を超える場合はリスク/影響で優先し、近い重複は統合する。
+3. **テーマ決定**  
+   `$ARGUMENTS` と回答でテーマ（セキュリティ・UX 等）・必須項目・カテゴリ骨子。捏造しない。
 
-6. **構造の参照**: タイトル・メタ・カテゴリ見出し・ID 形式はプロジェクトのチェックリスト慣例に従う。テンプレートがなければ、H1・目的/作成日のメタ・`##` カテゴリ内に `- [ ] CHK### 要件項目` を CHK001 から連番で並べる。
+4. **読込**  
+   FEATURE_SPEC **必須**。実装方針・タスクは UC .md 一番下。**checklists は任意**。UC のみなら生成スキップ可。
 
-7. **報告**: チェックリストファイルのフルパス・項目数・新規作成か既存への追記かを出力する。フォーカス領域・深さ・アクター/タイミング・ユーザーが明示した必須項目の反映を要約する。
+5. **生成（任意）**  
+   - `FEATURE_DIR/checklists/` を必要なら作成。短いファイル名（`ux.md`, `api.md`, `security.md`）
+   - 新規なら CHK001 から。既存は最後の ID の続きから**追記のみ**（削除・上書きしない）
 
-**重要**: 「チェックリスト」コマンドの実行ごとに、短い説明的なファイル名で新規作成または既存に追記する。これにより、複数タイプ（`ux.md`, `test.md`, `security.md` 等）のチェックリストを分けて持てる。乱雑にしないよう説明的なタイプを使い、不要になったものは整理する。
+   **各項目の観点**: 完全性・明確さ・一貫性・測定可能性・カバレッジ  
+   **カテゴリ例**: 完全性、明確さ、一貫性、受入品質、シナリオ、エッジ、非機能、依存・仮定、曖昧さ・矛盾
 
-## チェックリストタイプとサンプル項目の例
+   **書き方**: 質問形式。**禁止** — Verify/Test/Confirm + **実装挙動**、コード実行、正しく表示/動作、QA 手順、実装詳細。  
+   **推奨** — 「[要件] が [シナリオ] で定義されているか」「[曖昧語] が基準で明確化されているか」等。  
+   **トレーサビリティ**: 80% 以上に `[Spec §X.Y]` または `[Gap]` / `[曖昧さ]` / `[矛盾]` / `[仮定]`。  
+   40 件超はリスクで優先・重複統合。
 
-**UX 要件品質:** `ux.md` — 視覚的階層・枚数/配置・インタラクション状態・アクセシビリティ・画像読み込み失敗時のフォールバック・測定可能性 などが仕様で定義されているかを問う項目。
+6. **構造**  
+   H1・メタ・`##` カテゴリ内 `- [ ] CHK### …`（慣例がなければこの形）。
 
-**API 要件品質:** `api.md` — エラー応答形式・レート制限の閾値・認証の一貫性・リトライ/タイムアウト・バージョニング など。
+7. **報告**  
+   パス・項目数・新規/追記・フォーカス要約。
 
-**性能・セキュリティ要件品質:** `performance.md` / `security.md` — 定量指標・全クリティカルジャーニーでの目標・負荷条件・認証/データ保護/脅威モデル/コンプライアンス などが仕様で定義されているかを問う項目。
+**運用**: 実行ごとにタイプ別ファイルで追記。不要ファイルは人手で整理。
 
-## アンチ例: やってはいけないこと
+## 付録: タイプ例
 
-**❌ 誤 — 実装をテストしている**:
-- 「ランディングに 3 枚のエピソードカードが表示されることを確認する」
-- 「ホバーがデスクトップで正しく動くことをテストする」
+| ファイル | 焦点 |
+|----------|------|
+| ux.md | 視覚階層、配置、インタラクション状態、a11y、画像失敗時フォールバック |
+| api.md | エラー形式、レート制限、認証一貫、リトライ/タイムアウト |
+| performance.md / security.md | 定量指標、クリティカルジャーニー、脅威・コンプライアンスが**仕様で定義されているか** |
 
-**✅ 正 — 要件品質をテストしている**:
-- 「featured の枚数とレイアウトが明示されているか [完全性, Spec §FR-001]」
-- 「ホバー状態の要件が全インタラクティブ要素で一貫して定義されているか [一貫性, Spec §FR-003]」
-- 「視覚的階層の要件が客観的に測定できるか [測定可能性, Spec §FR-001]」
+## 付録: アンチ例
 
-**違い**: 誤りは「システムが正しく動くか」の検証。正解は「要件が正しく書かれているか」の検証。「X が動くか」ではなく「X が明確に仕様化されているか」を問う。
+| ❌ 実装テスト | ✅ 要件品質 |
+|---------------|-------------|
+| 3 枚のカードが表示されることを確認 | featured の枚数・レイアウトが仕様で明示されているか [完全性, Spec §…] |
+| ホバーが動くことをテスト | ホバー要件が全インタラクティブ要素で一貫しているか [一貫性] |
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。