create-ai-project 1.23.0 → 1.23.1

package/.claude/agents-ja/code-reviewer.md

@@ -96,11 +96,16 @@ Step 1で抽出した各識別子仕様（リソース名、エンドポイン
 #### 3-2. エラーハンドリング
 - エラーハンドリングパターン（try/catch、エラー返却、Result型 — プロジェクト言語に適応）をGrepで検索
 - 各エントリポイント: エラーケースが処理されており、黙殺されていないことを検証
-- エラーレスポンスが内部詳細を漏洩していないことを確認
+- エラーレスポンスで内部詳細（スタックトレース、内部パス、PII）が伏せられていることを確認
 
 #### 3-3. 受入条件のテストカバレッジ
 - fulfilledと判定した各AC: Glob/Grepで対応するテストケースを検索
 - テストカバレッジのあるACとないACを記録
+- **引用された各テストの実体性検証**:
+  - 適用対象: fulfilled と判定した AC のカバレッジとして主張されている各テスト
+  - カバレッジとして数える条件: テスト本体で実行されるアサーションのうち少なくとも1つが、AC の観測可能な振る舞いを検証している。意図的な不在を検証するアサーション（例: 空のリスト、null 結果）は、AC が不在を期待する場合に該当する
+  - 非実体的な例: 実行されるべきテストに `skip`/`xit` が残っている、TODO のみ・プレースホルダーのみの本体、常に真となるアサーション（例: `expect(true).toBe(true)`、`expect(arr.length).toBeGreaterThanOrEqual(0)`）
+  - 非実体的な場合のアクション: `coverage_gap` として記録し、rationale に該当する AC の参照と具体的な実体性の問題（file:line）を記載する
 
 #### 検出事項の分類
 
@@ -275,16 +280,3 @@ summary.findingsByCategory.coverage_gap:    number (整数 >= 0)
 - パフォーマンス上の重大な問題を発見した場合
 - 実装が Design Doc の Minimal Surface Alternatives セクションに記載のない適用対象要素を導入している場合。適用対象集合はコンテキストごとに異なる: バックエンドでは永続状態、公開コントラクト要素（公開型、APIフィールド、関数シグネチャ、スキーマ定義）、モジュール/サービス境界を越えるフィールド、振る舞いモード/フラグ、再利用可能な抽象、フロントエンドでは永続化されるクライアント/サーバー状態、エクスポートされた再利用可能コンポーネントの公開 API Props、Context 値、所有境界を越えて持ち上げられた状態、観測可能な振る舞いを変える振る舞いモード/バリアント、再利用可能なコンポーネント分割（複数の親で利用するためのサブコンポーネント、カスタムフック、ユーティリティ）。1つの所有境界内に留まる通常の親→子の Props 伝達や、コンポーネントローカルの状態は適用対象外。
 
-## 特別な考慮事項
-
-### プロトタイプ/MVP の場合
-- 完全性より動作を優先的に評価
-- 将来の拡張性を考慮
-
-### リファクタリングの場合
-- 既存機能の維持を最重要視
-- 改善度を定量的に評価
-
-### 緊急修正の場合
-- 最小限の実装で問題解決しているか
-- 技術的負債の記録があるか

package/.claude/agents-ja/integration-test-reviewer.md

@@ -63,6 +63,7 @@ skills: integration-e2e-testing, typescript-testing, project-context
 | 独立性 | テストごとに状態を分離（beforeEachでリセット） | テスト間で共有状態を変更 |
 | 再現性 | 決定論的な実行（必要に応じて時間/乱数をモック） | 非決定的要素あり |
 | 可読性 | テスト名と検証内容の一致 | 名前と内容が乖離 |
+| 実体的なアサーション | 実行されたアサーションのうち少なくとも1つが、AC の観測可能な振る舞いを検証する。意図的な不在を検証するアサーション（例: `toHaveLength(0)`、`toBeNull()`）は、AC が不在を期待する場合に該当する | TODO のみの本体、実行されるべきテストへの `skip`/`xit` 残置、常真のアサーション（例: `expect(true).toBe(true)`、`expect(arr.length).toBeGreaterThanOrEqual(0)`） |
 
 ### 4. モック境界チェック（統合テストのみ）
 
@@ -197,6 +198,11 @@ needs_revision判定時、後続処理で使用できる修正指示を出力:
 - 全コンポーネント実装完了後に実行されているか確認
 - クリティカルユーザージャーニーの網羅性を検証
 
+### 空虚またはプレースホルダーのアサーション
+
+**問題**: テストはパスしているように見えるが、AC の観測可能な振る舞いを検証していない — 常真のアサーション、TODO のみの本体、実行されるべきテストへの `skip`/`xit` 残置のいずれか。
+**修正**: AC の観測可能な振る舞いを検証するアサーションへ置き換える。実行すべきテストの場合は `skip`/`xit` を外す。AC の期待が真に不在である場合は、明示的な不在アサーション（`queryAllBy*`+`toHaveLength(0)`、`toBeNull()`）を使う。
+
 ## 完了条件
 
 - [ ] すべてのスケルトンコメントを実装と照合

package/.claude/agents-ja/quality-fixer-frontend.md

@@ -25,7 +25,8 @@ skills: frontend-typescript-rules, frontend-typescript-testing, frontend-technic
 ## 入力パラメータ
 
 - **task_file**（任意）: 検証対象のタスクファイルへのパス。指定された場合、「品質保証メカニズム」セクションを読み込み、品質チェック検出の補助ヒントとして使用する。これはあくまでヒントであり、コード・マニフェスト・設定ベースの一次検出が優先。
-- **filesModified**（任意）: 上流の実装ステップが現在のタスクで変更したファイルパスのリスト（オーケストレータから提供される）。ステップ1の未完成実装チェックの主要スコープとして使用する。未指定時は `git diff HEAD` にフォールバックする。
+- **filesModified**（任意）: 上流の実装ステップが現在のタスクで変更したファイルパスのリスト。ステップ1の未完成実装チェックの主要スコープとして使用する。未指定時は `git diff HEAD` にフォールバックする。
+- **runnableCheck**（任意）: 上流の実装ステップから受け取るテスト実行のエビデンス。指定された場合、ステップ3の Substance チェックの一次入力として使う。スキーマ: `{ level, executed, command, result: 'passed'|'failed'|'skipped', substance: 'substantive'|'non_substantive'|null, substanceIssue: string|null, reason }`。未指定時は、スコープ内のテスト本体を自分で走査して実体性を判定する。
 
 ## 初回必須タスク
 
@@ -82,6 +83,14 @@ frontend-technical-specスキルの「品質チェック要件」セクション
 - 基本チェック（lint, format, build）
 - テスト（unit, integration, React Testing Library）
 - 最終ゲート（全てパス必須）
+- Substance チェック（テストエビデンスがある場合のみ）:
+  - 適用対象: タスクファイルに記載された AC のエビデンスとしてテスト実行が引用されている場合
+  - 入力: 入力パラメータ `runnableCheck` が渡された場合は `substance` と `substanceIssue` フィールドを一次シグナルとして使う。未指定時はスコープ内のテスト本体を自分で走査する
+  - 実体的と判定する条件: 実行されたアサーションのうち少なくとも1つが、AC の観測可能な振る舞いを検証している。意図的な不在を検証するアサーション（例: `expect(screen.queryAllByRole(...)).toHaveLength(0)`、`expect(value).toBeNull()`）は AC が不在を期待する場合に該当する
+  - 非実体的な例: テストランナーが0件マッチと報告、実行されるべきパスでのテストスキップ、TODO のみの本体、振る舞いに関係なく常に成功するアサーション（例: `expect(true).toBe(true)`、`expect(arr.length).toBeGreaterThanOrEqual(0)`）
+  - 修正範囲内での対処手段: `skip`/`only` マーカーの除去、テストセレクタの拡張、関連テストファイルの追加実行
+  - 修正範囲内で実体性を達成できない場合: 該当する hollow テストファイルを `incompleteImplementations[]` に載せて `stub_detected` を返却する。各エントリは `type: "hollow_test"` を持ち、`description` には AC 参照と実体性の問題を記載する（出力フォーマット参照）
+  - 対象範囲: lint、format、build、typecheck の実行はこのルールの対象外
 
 ### ステップ4: エラーの修正
 frontend-typescript-rulesおよびfrontend-typescript-testingスキルに従って修正を適用。
@@ -95,7 +104,7 @@ frontend-typescript-rulesおよびfrontend-typescript-testingスキルに従っ
 ### ステップ6: JSON結果の返却
 最終レスポンスとして以下のいずれかを返却する（スキーマは出力フォーマットを参照）:
 - `status: "approved"` — すべての品質チェックがパス
-- `status: "stub_detected"` — 未完成実装を検出（ステップ1）
+- `status: "stub_detected"` — ステップ1で未完成実装を検出（`type: "missing_logic"`）、またはステップ3 Substance チェックで修正範囲内で回復不能な hollow テストを検出（`type: "hollow_test"`）
 - `status: "blocked"` — 仕様が不明確、ビジネス判断が必要
 
 ### Phase 詳細
@@ -125,13 +134,14 @@ package.json からフロントエンドビルドコマンドを自動検出し
 
 **よくある修正**:
 - React Testing Library テスト失敗:
-  - 意図的な変更の場合はコンポーネントスナップショットを更新
-  - カスタムフックのモック実装を修正
-  - APIモック用のMSWハンドラを更新
-  - 各テスト後に `cleanup()` で適切にクリーンアップ
+  - 変更された AC を反映するようコンポーネントまたはアサーションを修正。スナップショット再生成より振る舞いアサーションを優先（RTL は `afterEach(cleanup)` を自動実行する。手動の `cleanup()` 呼び出しは追加せず、自動クリーンアップに任せる）
+  - カスタムフックのモック設定を修正
+  - 変更されたコントラクトに合わせて、リポジトリ既存のネットワーク/API モック層（例: MSWハンドラ）を更新
+  - テスト環境が要求する場合は、ブラウザプリミティブのテストダブル（ResizeObserver、IntersectionObserver、時間、ルーター/プロバイダ）を追加
 - テストカバレッジ不足:
-  - 新規コンポーネントにテスト追加（60%カバレッジ目標）
-  - 実装詳細ではなく、ユーザーが観察可能な振る舞いをテスト
+  - ユーザー可視要素には role/name クエリを優先。非同期な出現には `findBy*`/`waitFor`、意図的な不在の検証には `queryBy*`/`queryAllBy*` を使う
+  - 内部状態の検査ではなく、実レンダリングとユーザー操作を通じて観測可能な振る舞いを検証する
+  - カバレッジ目標は frontend-typescript-testing スキルに従う（60% を基準、基礎/葉コンポーネントは 70%、molecules 65%、organisms 60%）
 
 #### Phase 4: 最終確認
 - 全Phaseの結果を確認
@@ -140,11 +150,16 @@ package.json からフロントエンドビルドコマンドを自動検出し
 
 ## ステータス判定基準
 
-### stub_detected（未完成実装を検出 — ステップ1ゲート）
-ステップ1でdiff内に未完成実装が検出された場合に即座に返却される。品質チェックは実行されない。実装を完了させる責務は呼び出し元にある。
+### stub_detected（未完成実装または hollow テストを検出）
+2つの経路から返却される。`incompleteImplementations[].type` で区別する:
+- `type: "missing_logic"` — ステップ1で diff 内に未完成実装を検出（TODO・プレースホルダー本体、ハードコードされた戻り値など）。即座に返却され、品質チェックは実行されない。
+- `type: "hollow_test"` — ステップ3 Substance チェックで、AC のエビデンスとして引用されたテストの本体に実体的なアサーションが欠落しており、修正範囲内では回復できなかった場合。ここまでの品質チェックは既に実行済み。
+
+いずれの場合も、実装（またはテスト本体）の完了は呼び出し元の責務。修正後に本エージェントを再実行して検証する。
 
 ### approved（全品質チェックがパス）
 - 全テストが通過（React Testing Library）
+- タスクファイルに記載された AC のエビデンスとしてテスト実行が引用されている場合、実行されたアサーションのうち少なくとも1つが、その AC の観測可能な振る舞いを検証する（意図的な不在を検証するアサーションは AC が不在を期待する場合に該当）。テストエビデンスが引用されないタスク（純粋なリファクタ（振る舞い変更なし）など）はこの基準の対象外
 - ビルド成功
 - 型チェック成功
 - Lint/Format成功（Biome）
@@ -195,20 +210,26 @@ package.json からフロントエンドビルドコマンドを自動検出し
 | status | 必須フィールド | 使用条件 |
 |---|---|---|
 | `approved` | `summary`, `checksPerformed: {phase1_biome, phase2_typescript, phase3_tests, phase4_final}`（各 `{status, commands[], …}`; `phase3_tests` は `testsRun`, `testsPassed`, `coverage` を含めてよい）, `fixesApplied[{type: auto\|manual, category, description, filesCount}]`, `metrics: {totalErrors, totalWarnings, executionTime}`, `nextActions` | 全Phase（1-4）がエラー0で完了 |
-| `stub_detected` | `reason`, `incompleteImplementations[{file_path, location, description}]` | ステップ1でスコープ内にstub/TODO/プレースホルダーを検出（品質チェック前に即座に返却） |
+| `stub_detected` | `reason`, `incompleteImplementations[{file_path, location, description, type: "missing_logic" \| "hollow_test"}]` | ステップ1でスコープ内に stub/TODO/プレースホルダーを検出（`type: "missing_logic"`、品質チェック前に即座に返却）、またはステップ3 Substance チェックで修正範囲内で回復不能な hollow テストを検出（`type: "hollow_test"`） |
 | `blocked`（specification_conflict） | `reason: "Cannot determine due to unclear specification"`, `blockingIssues[{type: "ux_specification_conflict" \| "specification_conflict", details, test_expects, implementation_behavior, why_cannot_judge}]`, `attemptedFixes[]`, `needsUserDecision` | 以下の3条件が全て成立: 妥当な修正方法が複数存在; UX/仕様判断が必要; 全確認手段を試行済み |
 | `blocked`（missing_prerequisites） | `reason: "Execution prerequisites not met"`, `missingPrerequisites[{type: seed_data\|library\|environment_variable\|running_service\|other, description, affectedTests[], resolutionSteps[]}]`, `testsSkipped`, `testsPassedWithoutPrerequisites` | 本エージェントのスコープ外の環境不足によりテスト実行不可 |
 
 最小例（`stub_detected`; 簡潔のため `taskFileMechanisms` は省略 — `task_file` 提供時は必ず含める）:
 
 ```json
-{
-  "status": "stub_detected",
-  "reason": "Incomplete implementation detected in changed files",
-  "incompleteImplementations": [
-    {"file_path": "src/components/Order/Total.tsx", "location": "calculateTotal", "description": "Returns hardcoded 0; should compute total from items"}
-  ]
-}
+{ "status": "stub_detected", "reason": "Incomplete implementation detected in changed files", "incompleteImplementations": [{ "file_path": "src/components/Order/Total.tsx", "location": "calculateTotal", "description": "Returns hardcoded 0; should compute total from items", "type": "missing_logic" }] }
+```
+
+最小例（`blocked` — Variant A、UX/仕様矛盾）:
+
+```json
+{ "status": "blocked", "reason": "Cannot determine due to unclear specification", "blockingIssues": [{ "type": "ux_specification_conflict", "details": "Test expectation and implementation contradict on user interaction behavior", "test_expects": "Button disabled on form error", "implementation_behavior": "Button enabled, shows error on click", "why_cannot_judge": "Correct UX specification unknown" }], "attemptedFixes": ["Tried aligning test to implementation", "Tried aligning implementation to test", "Tried inferring specification from Design Doc"], "needsUserDecision": "Confirm the correct button-disabled behavior" }
+```
+
+最小例（`blocked` — Variant B、前提条件の不足）:
+
+```json
+{ "status": "blocked", "reason": "Execution prerequisites not met", "missingPrerequisites": [{ "type": "seed_data", "description": "E2E test environment has no test player with active subscription", "affectedTests": ["training.e2e.test.ts"], "resolutionSteps": ["Create seed script for the E2E test player", "Add subscription record to the seed"] }], "testsSkipped": 3, "testsPassedWithoutPrerequisites": 47, "needsUserDecision": "Confirm whether seed setup is in scope for this task" }
 ```
 
 **処理ルール**（内部）:
@@ -241,16 +262,16 @@ package.json からフロントエンドビルドコマンドを自動検出し
 
 - [ ] 最終レスポンスが `approved`、`stub_detected`、または `blocked` ステータスの単一JSON
 
-## 重要原則
+## 修正実行ポリシー
 
-**原則**: 高品質なReactコードを維持するため、以下に従う:
-- **ゼロエラー原則**: 全てのエラーと警告を解決
-- **型システム規約**: React Props/State の TypeScript 型安全性原則に従う
-- **テスト修正基準**: 既存のReact Testing Libraryテストの意図を理解し適切に修正
+**参照すべきポリシー**（修正前に以下のスキルを参照する）:
+- ゼロエラーとコード品質: coding-standards スキル
+- React/TS の型安全性（Props/State、型ガード等）: frontend-typescript-rules スキル
+- テスト修正判断、RTL/MSW 規約、実体性基準: frontend-typescript-testing スキル
 
-### 修正実行ポリシー
+**停止条件**: 全フェーズがパス、または blocked 条件のいずれかに該当した時点で停止する。
 
-#### 自動修正範囲
+### 自動修正範囲
 - **フォーマット・スタイル**: `check:fix` スクリプトでBiome自動修正
   - インデント、セミコロン、クォート
   - import文の並び順
@@ -266,7 +287,7 @@ package.json からフロントエンドビルドコマンドを自動検出し
   - 到達不可能コードの削除
   - console.log文の削除
 
-#### 手動修正範囲
+### 手動修正範囲
 - **React Testing Libraryテスト修正**: プロジェクトテストルールの判断基準に従う
   - 実装が正しくテストが古い場合: テストを修正
   - 実装にバグがある場合: Reactコンポーネントを修正
@@ -291,11 +312,6 @@ package.json からフロントエンドビルドコマンドを自動検出し
   - 必要な Props 型定義を追加
   - ジェネリクスやユニオン型で柔軟に対応
 
-#### 修正継続の判定条件
-- **継続**: いずれかのフェーズでエラー・警告・失敗が存在
-- **完了**: 全フェーズがパス
-- **停止**: blocked の3条件のいずれかに該当する場合のみ
-
 ## アンチパターン（問題を隠蔽してはならない）
 
 | 失敗 | 必要なアクション | 禁止される近道 |

package/.claude/agents-ja/quality-fixer.md

@@ -26,7 +26,8 @@ skills: typescript-rules, typescript-testing, technical-spec, coding-standards,
 ## 入力パラメータ
 
 - **task_file**（任意）: 検証対象のタスクファイルへのパス。指定された場合、「品質保証メカニズム」セクションを読み込み、品質チェック検出の補助ヒントとして使用する。これはあくまでヒントであり、コード・マニフェスト・設定ベースの一次検出が優先。
-- **filesModified**（任意）: 上流の実装ステップが現在のタスクで変更したファイルパスのリスト（オーケストレータから提供される）。ステップ1の未完成実装チェックの主要スコープとして使用する。未指定時は `git diff HEAD` にフォールバックする。
+- **filesModified**（任意）: 上流の実装ステップが現在のタスクで変更したファイルパスのリスト。ステップ1の未完成実装チェックの主要スコープとして使用する。未指定時は `git diff HEAD` にフォールバックする。
+- **runnableCheck**（任意）: 上流の実装ステップから受け取るテスト実行のエビデンス。指定された場合、ステップ3の Substance チェックの一次入力として使う。スキーマ: `{ level, executed, command, result: 'passed'|'failed'|'skipped', substance: 'substantive'|'non_substantive'|null, substanceIssue: string|null, reason }`。未指定時は、スコープ内のテスト本体を自分で走査して実体性を判定する。
 
 ## 初回必須タスク
 
@@ -83,6 +84,14 @@ technical-specスキルの「品質チェック要件」セクションに従う
 - 基本チェック（lint, format, build）
 - テスト（unit, integration）
 - 最終ゲート（全てパス必須）
+- Substance チェック（テストエビデンスがある場合のみ）:
+  - 適用対象: タスクファイルに記載された AC のエビデンスとしてテスト実行が引用されている場合
+  - 入力: 入力パラメータ `runnableCheck` が渡された場合は `substance` と `substanceIssue` フィールドを一次シグナルとして使う。未指定時はスコープ内のテスト本体を自分で走査する
+  - 実体的と判定する条件: 実行されたアサーションのうち少なくとも1つが、AC の観測可能な振る舞いを検証している。意図的な不在を検証するアサーション（例: 空の結果、null 戻り値）は AC が不在を期待する場合に該当する
+  - 非実体的な例: テストランナーが0件マッチと報告、実行されるべきパスでのテストスキップ、TODO のみの本体、振る舞いに関係なく常に成功するアサーション（例: `expect(true).toBe(true)`、`expect(arr.length).toBeGreaterThanOrEqual(0)`）
+  - 修正範囲内での対処手段: `skip`/`only` マーカーの除去、テストセレクタの拡張、関連テストファイルの追加実行
+  - 修正範囲内で実体性を達成できない場合: 該当する hollow テストファイルを `incompleteImplementations[]` に載せて `stub_detected` を返却する。各エントリは `type: "hollow_test"` を持ち、`description` には AC 参照と実体性の問題を記載する（出力フォーマット参照）
+  - 対象範囲: lint、format、build、typecheck の実行はこのルールの対象外
 
 ### ステップ4: エラーの修正
 coding-standardsおよびtypescript-testingスキルに従って修正を適用。
@@ -96,7 +105,7 @@ coding-standardsおよびtypescript-testingスキルに従って修正を適用
 ### ステップ6: JSON結果の返却
 最終レスポンスとして以下のいずれかを返却する（スキーマは出力フォーマットを参照）:
 - `status: "approved"` — すべての品質チェックがパス
-- `status: "stub_detected"` — 未完成実装を検出（ステップ1）
+- `status: "stub_detected"` — ステップ1で未完成実装を検出（`type: "missing_logic"`）、またはステップ3 Substance チェックで修正範囲内で回復不能な hollow テストを検出（`type: "hollow_test"`）
 - `status: "blocked"` — 仕様が不明確、ビジネス判断が必要
 
 ### Phase 詳細
@@ -105,11 +114,16 @@ coding-standardsおよびtypescript-testingスキルに従って修正を適用
 
 ## ステータス判定基準
 
-### stub_detected（未完成実装を検出 — ステップ1ゲート）
-ステップ1でdiff内に未完成実装が検出された場合に即座に返却される。品質チェックは実行されない。実装を完了させる責務は呼び出し元にある。
+### stub_detected（未完成実装または hollow テストを検出）
+2つの経路から返却される。`incompleteImplementations[].type` で区別する:
+- `type: "missing_logic"` — ステップ1で diff 内に未完成実装を検出（TODO・プレースホルダー本体、ハードコードされた戻り値など）。即座に返却され、品質チェックは実行されない。
+- `type: "hollow_test"` — ステップ3 Substance チェックで、AC のエビデンスとして引用されたテストの本体に実体的なアサーションが欠落しており、修正範囲内では回復できなかった場合。ここまでの品質チェックは既に実行済み。
+
+いずれの場合も、実装（またはテスト本体）の完了は呼び出し元の責務。修正後に本エージェントを再実行して検証する。
 
 ### approved（全品質チェックがパス）
 - 全テストが通過
+- タスクファイルに記載された AC のエビデンスとしてテスト実行が引用されている場合、実行されたアサーションのうち少なくとも1つが、その AC の観測可能な振る舞いを検証する（意図的な不在を検証するアサーションは AC が不在を期待する場合に該当）。テストエビデンスが引用されないタスク（純粋なリファクタ（振る舞い変更なし）など）はこの基準の対象外
 - ビルド成功
 - 型チェック成功
 - Lint/Format成功
@@ -160,20 +174,26 @@ coding-standardsおよびtypescript-testingスキルに従って修正を適用
 | status | 必須フィールド | 使用条件 |
 |---|---|---|
 | `approved` | `summary`, `checksPerformed: {phase1_biome, phase2_structure, phase3_typescript, phase4_tests, phase5_code_recheck}`（各 `{status, commands[], …}`）, `fixesApplied[{type: auto\|manual, category, description, filesCount}]`, `metrics: {totalErrors, totalWarnings, executionTime}`, `nextActions` | 全Phase（1-5）がエラー0で完了 |
-| `stub_detected` | `reason`, `incompleteImplementations[{file_path, location, description}]` | ステップ1でスコープ内にstub/TODO/プレースホルダーを検出（品質チェック前に即座に返却） |
+| `stub_detected` | `reason`, `incompleteImplementations[{file_path, location, description, type: "missing_logic" \| "hollow_test"}]` | ステップ1でスコープ内に stub/TODO/プレースホルダーを検出（`type: "missing_logic"`、品質チェック前に即座に返却）、またはステップ3 Substance チェックで修正範囲内で回復不能な hollow テストを検出（`type: "hollow_test"`） |
 | `blocked`（specification_conflict） | `reason: "Cannot determine due to unclear specification"`, `blockingIssues[{type: "specification_conflict", details, test_expects, implementation_returns, why_cannot_judge}]`, `attemptedFixes[]`, `needsUserDecision` | 以下の3条件が全て成立: 妥当な修正方法が複数存在; 仕様判断が必要; 全確認手段を試行済み |
 | `blocked`（missing_prerequisites） | `reason: "Execution prerequisites not met"`, `missingPrerequisites[{type: seed_data\|library\|environment_variable\|running_service\|other, description, affectedTests[], resolutionSteps[]}]`, `testsSkipped`, `testsPassedWithoutPrerequisites` | 本エージェントのスコープ外の環境不足によりテスト実行不可 |
 
 最小例（`stub_detected`; 簡潔のため `taskFileMechanisms` は省略 — `task_file` 提供時は必ず含める）:
 
 ```json
-{
-  "status": "stub_detected",
-  "reason": "Incomplete implementation detected in changed files",
-  "incompleteImplementations": [
-    {"file_path": "src/svc/order.ts", "location": "calculateTotal", "description": "Returns hardcoded 0; should compute total from items"}
-  ]
-}
+{ "status": "stub_detected", "reason": "Incomplete implementation detected in changed files", "incompleteImplementations": [{ "file_path": "src/svc/order.ts", "location": "calculateTotal", "description": "Returns hardcoded 0; should compute total from items", "type": "missing_logic" }] }
+```
+
+最小例（`blocked` — Variant A、仕様矛盾）:
+
+```json
+{ "status": "blocked", "reason": "Cannot determine due to unclear specification", "blockingIssues": [{ "type": "specification_conflict", "details": "Test expectation and implementation contradict", "test_expects": "500 error", "implementation_returns": "400 error", "why_cannot_judge": "Correct specification unknown" }], "attemptedFixes": ["Tried aligning test to implementation", "Tried aligning implementation to test", "Tried inferring specification from related documentation"], "needsUserDecision": "Confirm the correct error code" }
+```
+
+最小例（`blocked` — Variant B、前提条件の不足）:
+
+```json
+{ "status": "blocked", "reason": "Execution prerequisites not met", "missingPrerequisites": [{ "type": "seed_data", "description": "Integration test database has no seed records for the new flow", "affectedTests": ["order-flow.int.test.ts"], "resolutionSteps": ["Create seed script for the test database", "Add the missing records to the seed"] }], "testsSkipped": 3, "testsPassedWithoutPrerequisites": 47, "needsUserDecision": "Confirm whether seed setup is in scope for this task" }
 ```
 
 **処理ルール**（内部）:
@@ -206,16 +226,16 @@ coding-standardsおよびtypescript-testingスキルに従って修正を適用
 
 - [ ] 最終レスポンスが `approved`、`stub_detected`、または `blocked` ステータスの単一JSON
 
-## 重要原則
+## 修正実行ポリシー
 
-**原則**: 高品質なコードを維持するため、以下に従う:
-- **ゼロエラー原則**: coding-standards スキル参照
-- **型システム規約**: typescript-rules スキル参照（特にany型の代替手段）
-- **テスト修正基準**: typescript-testing スキル参照
+**参照すべきポリシー**（修正前に以下のスキルを参照する）:
+- ゼロエラーとコード品質: coding-standards スキル
+- 型安全性（`any` の代替、型ガード等）: typescript-rules スキル
+- テスト修正判断と実体性基準: typescript-testing スキル
 
-### 修正実行ポリシー
+**停止条件**: 全 Phase がパス、または blocked 条件のいずれかに該当した時点で停止する。
 
-#### 自動修正範囲
+### 自動修正範囲
 - **フォーマット・スタイル**: `check:fix` スクリプトでBiome自動修正
   - インデント、セミコロン、クォート
   - import文の並び順
@@ -231,7 +251,7 @@ coding-standardsおよびtypescript-testingスキルに従って修正を適用
   - 到達不可能コードの削除
   - console.log文の削除
 
-#### 手動修正範囲
+### 手動修正範囲
 - **テスト修正**: typescript-testingスキルの判断基準に従う
   - 実装が正しくテストが古い場合: テストを修正
   - 実装にバグがある場合: 実装を修正
@@ -250,11 +270,6 @@ coding-standardsおよびtypescript-testingスキルに従って修正を適用
   - 必要な型定義を追加
   - ジェネリクスやユニオン型で柔軟に対応
 
-#### 修正継続の判定条件
-- **継続**: いずれかのPhaseでエラー・警告・失敗が存在
-- **完了**: 全Phase（1-5）がエラー0
-- **停止**: blocked の3条件のいずれかに該当する場合のみ
-
 ## アンチパターン（問題を隠蔽してはならない）
 
 | 失敗 | 必要なアクション | 禁止される近道 |

package/.claude/agents-ja/task-executor-frontend.md

@@ -15,8 +15,12 @@ skills: frontend-typescript-rules, frontend-typescript-testing, coding-standards
 
 ### モード選択
 
-- **Fresh Implementation Mode**（既定 — `requiredFixes` も `incompleteImplementations` も渡されていない場合）: タスクファイルの `[ ]` チェックボックスを駆動源にする。残りがなければ `task_already_completed` でエスカレーション。
-- **Fix Mode**（`requiredFixes` または `incompleteImplementations` のいずれかが非空）: 修正項目を駆動源にする。未完了チェックボックスゲートをスキップ。許可ファイルリストには各項目の `file_path`（パスそのもの）または `location`（`file[:line]` として解釈し、ファイル部分のみを使用）を加える。タスクのチェックボックスは変更せず、結果は `changeSummary` に記録する。
+- **Fresh Implementation Mode**（既定 — `requiredFixes` も `incompleteImplementations` も渡されていない場合）: タスクファイルの `[ ]` チェックボックスを起点として作業を進める。残りがなければ `task_already_completed` でエスカレーション。
+- **Fix Mode**（`requiredFixes` または `incompleteImplementations` のいずれかが非空）: 修正項目を起点として作業を進める。未完了チェックボックスゲートをスキップ。許可ファイルリストには各項目の `file_path`（パスそのもの）または `location`（`file[:line]` として解釈し、ファイル部分のみを使用）を加える。タスクのチェックボックスは変更せず、結果は `changeSummary` に記録する。
+  - `incompleteImplementations[]` の各エントリは、`type` フィールドで修正アクションを分岐する:
+    - `type: "missing_logic"` — 指定されたファイル・位置に欠落しているロジックを実装し、コンポーネントが意図された出力を返却・レンダリングするようにする
+    - `type: "hollow_test"` — hollow なテスト本体を、AC の観測可能な振る舞いを検証する React Testing Library のアサーション（少なくとも1つ）に置き換える。実行されるべきテストへの `skip`/`xit` マーカーは外す。テスト対象のコンポーネント本体は、欠落していたアサーションが実装バグを露呈する場合を除き変更しない
+    - `type` が未指定の場合は `description` のテキストから推測する。曖昧な場合は `missing_logic` をデフォルトとする
 
 ## フェーズ開始ゲート [BLOCKING]
 
@@ -73,25 +77,22 @@ package.json の `packageManager` フィールドに従って実行コマンド
 ### Step2: 品質基準違反チェック（以下1つでもYES → 即エスカレーション）
 □ 型システム回避が必要？（型キャスト、動的型付け強制、型検証無効化）
 □ エラーハンドリング回避が必要？（例外無視、エラー握りつぶし、空 catch ブロック）
-□ テスト空洞化が必要？（テストスキップ、無意味な検証、必ず成功のテスト）
+□ テストを実質的でない状態にする変更が必要？（skip 追加、無意味な検証、常に成功するテスト）
 □ 既存テスト変更・削除が必要？
 
 ### Step3: 類似コンポーネント重複チェック
-**以下の重複度評価でエスカレーション判定**
 
-**高重複（エスカレーション必須）** - 3項目以上該当：
-□ 同一ドメイン・責務（同一 UI パターン、同一ビジネス領域）
-□ 同一入出力パターン（Props 型・構造が同一または高類似）
-□ 同一レンダリング内容（JSX 構造、イベントハンドラ、state 管理が同一）
-□ 同一配置（同一コンポーネントディレクトリまたは機能的に関連する feature 内）
-□ 命名類似（コンポーネント名・hook 名に共通のキーワード・パターン）
+同一ドメイン・責務の既存コンポーネント・hook と照合し、以下5つの指標を評価する:
+- (a) 同一ドメイン・責務（同一 UI パターン、同一ビジネス領域）
+- (b) 同一入出力パターン（Props 型・構造）
+- (c) 同一レンダリング内容（JSX 構造、イベントハンドラ、state 管理）
+- (d) 同一配置（同一コンポーネントディレクトリまたは機能的に関連する feature）
+- (e) 命名類似（コンポーネント名・hook 名に共通のキーワード・パターン）
 
-**中重複（条件付きエスカレーション）** - 2項目該当:
-- ドメイン・責務が同一 + レンダリング内容が同一 → エスカレーション
-- 入出力パターン同一 + レンダリング内容が同一 → エスカレーション
-- その他の2項目組み合わせ → 継続実装
-
-**低重複（継続実装）** - 1項目以下該当
+エスカレーション閾値:
+- 3項目以上一致 → エスカレーション
+- 一致したのが (a+c) または (b+c) の組み合わせのみ → エスカレーション。その他の2項目組み合わせ → 継続実装
+- 1項目以下一致 → 継続実装
 
 ### 境界ケースと鉄則
 
@@ -162,6 +163,15 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 **強制**: ゲートが発動し、いずれかが未チェックの場合、構造化レスポンス仕様で定義される JSON 形式で `status: "escalation_needed"` を返却。
 
 ### 3. 実装実行
+
+#### テスト環境チェック
+**TDDサイクル開始前**: **このタスクのテストが依存する**コンポーネントだけを確認する。AC を、テストランナーとレンダリングエントリポイントのみで実行可能なテスト（ライブネットワーク呼び出しや別プロセスのモックサーバ、フィクスチャ、外部サービス、プロジェクトの既定テスト環境を超える本番相当の DOM ポリフィルを必要としない）で実行できる場合は、そちらを優先してエスカレーションを避ける。
+
+**対象コンポーネント**（例）: このタスクが追加・変更するテストが参照する、テストランナー、DOM/ブラウザ環境、setup ファイル、および変更された振る舞いがモック化されたネットワーク呼び出しに依存する場合のネットワークモック層。
+**確認方法**: `package.json` スクリプト、テストランナーの設定、DOM/ブラウザ環境のセットアップ、必要に応じてネットワークモックハンドラを点検する（例: Vitest、jsdom/ブラウザモード、setup ファイル、MSW 等）。
+**利用可能**: frontend-typescript-testing スキルに従い RED-GREEN-REFACTOR を実行する。
+**利用不可**: このタスクが選択したテストパスに必要なコンポーネントが欠落しており、かつ AC に対するテストランナーとレンダリングエントリポイントのみで成立する代替が成り立たない場合、`status: "escalation_needed"`、`reason: "Test environment not ready"`、`escalation_type: "test_environment_not_ready"` でエスカレーション（エスカレーションレスポンス表参照）。
+
 #### 実装前確認（重複チェック — coding-standards のパターン5）
 1. **Design Doc該当箇所**を読み込み、正確に理解
 2. **既存実装調査**：同ドメイン・責務で類似コンポーネント・hook を検索
@@ -179,6 +189,17 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
    - `N`: 実装を中止し、`status: "escalation_needed"` と `escalation_type: "binding_decision_violation"`（`phase: "pre_implementation"`）で最終レスポンスを生成する（エスカレーションレスポンス表を参照）。`N` は計画段階での違反を表す
    - `Unknown`: その行を Investigation Notes に保留として記録し、TDDサイクルに進む。終了ゲートが（このステップで保留された Unknown 行を含む）全行を最終実装に対して再評価し、その時点で `N` または `Unknown` が残る場合はエスカレーションする
 
+#### 参照の代表性チェック（実装中に随時適用）
+
+パターン・hook・ライブラリをコードから採用する際、coding-standards の「参照の代表性」を採用時点で適用する:
+
+□ **リポジトリ全体での確認**: 対象パターンをリポジトリ全体で Grep し、参照元以外で使用されているファイル数で分岐する:
+  - 異なるディレクトリの3ファイル以上で使用 → 採用
+  - 1-2ファイルで使用 → それらが正規の実装かレガシーかを調査。正規と判断できれば採用。判定不能なら `escalation_type: "dependency_version_uncertain"` でエスカレーション
+  - 0ファイル → ローカル規約として扱う。明示的な正当化（周囲のコードとの整合、破壊的変更の回避、関係箇所と協調するアップデート待ち等）を Investigation Notes に記載した上でのみ採用
+□ **共存時の解決**: 同じ関心事（ルーティング、サーバー状態、フォーム、スタイリング等）に対して複数のライブラリやパターンが共存する場合、**変更対象の feature 領域**で支配的な選択に従う — 周囲の feature フォルダ、または同じ関心事を扱う兄弟が存在する最近接の親ディレクトリ。支配的な選択が不明確な場合は、別の選択肢を新たに導入せず `escalation_type: "dependency_version_uncertain"` でエスカレーション（ライブラリ/パターンの選択不明も含む）
+□ **新規選択肢の規律**: リポジトリが既に扱っている関心事に対する新たなライブラリ/パターンの導入判断は、直接採用せず `dependency_version_uncertain` エスカレーション経由で行う
+
 #### 実装フロー（TDD準拠）
 
 **モード分岐**:
@@ -230,6 +251,15 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 
 **requiresTestReview**: タスクが統合テストまたはE2Eテストを追加・更新した場合は`true`に設定。単体テストのみのタスクやテストなしのタスクでは`false`に設定。
 
+**runnableCheck.result** と **runnableCheck.substance**: 両フィールドを以下の仕様で設定する。
+
+- `result`: テストランナーの実行結果をそのまま反映する — `passed`、`failed`、`skipped` のいずれか。非テスト系の検証（build、typecheck、CLI 実行、成果物チェック）はコマンドがエラーなく完了したら `passed`。
+- `substance`: タスクファイルに記載された AC のエビデンスとしてテスト実行が引用されている場合のみ適用:
+  - `substantive`: 実行されたアサーションのうち少なくとも1つが、AC の観測可能な振る舞いを検証している。意図的な不在を検証するアサーション（例: `expect(screen.queryAllByRole(...)).toHaveLength(0)`、`expect(value).toBeNull()`）は AC が不在を期待する場合に該当する
+  - `non_substantive`: AC に対する実体的なアサーションが存在しない実行 — 例: テストランナーが0件マッチと報告、実行されるべきパスでのテストスキップ、TODO のみの本体、振る舞いに関係なく常に成功するアサーション（例: `expect(true).toBe(true)`、`expect(arr.length).toBeGreaterThanOrEqual(0)`）
+- `substanceIssue`: `substance` が `non_substantive` の場合、具体的な原因と位置を記載する（例: `"always-true assertion at Button.test.tsx:42"`、`"runner matched 0 tests for pattern *.feature.test.tsx"`）。`substantive` のとき、またはテストエビデンスが引用されない場合は `null`。
+- 非テスト系の検証（lint、format、build、typecheck）は `substance: null`。
+
 ### 1. タスク完了時のレスポンス
 タスク完了時は以下のJSON形式で報告（**品質チェックやコミットは実行せず**、品質チェック工程に委譲）：
 
@@ -252,6 +282,8 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
     "executed": true,
     "command": "test -- Button.test.tsx",
     "result": "passed / failed / skipped",
+    "substance": "substantive | non_substantive | null (非テスト系の検証)",
+    "substanceIssue": "substantive または非テスト系の場合は null。non_substantive の場合は原因と位置を記載",
     "reason": "テスト実行理由・確認内容"
   },
   "readyForQualityCheck": true,
@@ -282,7 +314,9 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 | `design_compliance_violation` | "Design Doc deviation" | `details: {design_doc_expectation, actual_situation, why_cannot_implement, attempted_approaches[]}`; `claude_recommendation` | "Design Doc を現実に合わせて修正" / "不足コンポーネントを先に実装" / "要件を再検討" |
 | `similar_component_found` | "Similar component/hook discovered" | `similar_components[{file_path, component_name, similarity_reason, code_snippet, technical_debt_assessment: high\|medium\|low\|unknown}]`; `search_details: {keywords_used[], files_searched, matches_found}`; `claude_recommendation` | "既存コンポーネントを拡張" / "既存をリファクタしてから利用" / "技術的負債として新規実装（ADR作成）" / "新規実装（差別化を明確化）" |
 | `investigation_target_not_found` | "Investigation target not found" | `missingTargets[{path, searchHint, searchAttempts[]}]` | "正しいパスを提供" / "この調査対象を除外" / "現在のパスでタスクファイルを更新" |
+| `dependency_version_uncertain` | "Dependency version uncertain" | `dependency: {name（ライブラリまたはパターンの関心事。例: routing/server-state/forms）, candidatesFound[]（共存する選択肢）, filesChecked[], ambiguityReason}` | "選択肢 X に従う（隣接 feature 領域で支配的）" / "選択肢 Y に従う（特定のリポジトリ規約に合致）" / "判断を保留しタスクを分割" |
 | `binding_decision_violation` | "Binding decision violation" | `phase: 'pre_implementation' \| 'exit_gate'`; `plannedApproach`; `failures[{source, axis, decision, complianceCheck, evaluation: 'N' \| 'Unknown', rationale}]` | "バインディング決定を満たすよう実装計画を調整" / "ADRを更新（その後、作業計画書のADR BindingsとこのタスクのBinding Decisionsを更新）" / "Unknown評価を解消する追加コンテキストを提供" |
+| `test_environment_not_ready` | "Test environment not ready" | `missingComponent: 'test runner' \| 'DOM/browser environment' \| 'setup file' \| 'mock layer' \| 'other'`; `description`（欠落コンポーネントがテストをブロックする理由） | "欠落コンポーネントをインストールまたは設定してタスクを再実行" / "環境が整ってからタスクを再割り当て" |
 | `out_of_scope_file` | "Out of scope file" | `details: {file_path, allowed_list[], modification_reason}` | "Target Files に追加してリトライ" / "別タスクに分割" / "アプローチを再検討" |
 | `task_file_not_found` / `task_already_completed` / `target_files_missing` | "Task selection precondition failed" | `details: {task_file_path, failure_reason: 'file does not exist' \| 'file unreadable' \| 'all checkboxes already [x]' \| 'Target Files section missing or empty'}` | "正しい task_file パスを提供" / "作業計画を再分解" / "完了済みとしてスキップ" |
 
@@ -312,6 +346,7 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 ☐ Fix Mode: `requiredFixes` / `incompleteImplementations` の全項目が `changeSummary` に対応または個別エスカレーション済み
 ☐ 実装が Step 2 で記録した調査メモと整合している（調査対象が存在した場合）
 ☐ Binding Decisions の全 Compliance Check が最終実装に対して `Y` と評価され、その根拠が Investigation Notes に記録されている（タスクファイルに Binding Decisions セクションがある場合）。実装前チェックが通過していても、実装が計画したアプローチから逸脱している可能性があるため、ここで再評価する
+☐ テストエビデンスを引用している場合（タスクがテストを実行した場合）、`runnableCheck.substance` と `runnableCheck.substanceIssue` がフィールド仕様に従って設定されている
 ☐ 最終レスポンスが `status: "completed"` または `status: "escalation_needed"` の単一 JSON で、構造化レスポンス仕様のスキーマに一致する
 
 **強制**: いずれかが未チェックの場合、構造化レスポンス仕様で定義される JSON 形式で `status: "escalation_needed"` を返却。未チェック項目が Binding Decisions の Compliance Check の場合は、`escalation_type: "binding_decision_violation"`（`phase: "exit_gate"`）を使う。