takt 0.41.0 → 0.43.0

package/builtins/ja/facets/instructions/implement-maintenance.md

@@ -0,0 +1,72 @@
+計画に従い、既存契約を保った最小差分で実装してください。
+Workflow Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。
+Report Directory内のレポートを一次情報として参照してください。不足情報の補完が必要な場合に限り、Previous Responseや会話履歴を補助的に参照して構いません（Previous Responseは提供されない場合があります）。情報が競合する場合は、Report Directory内のレポートと実際のファイル内容を優先してください。
+
+**重要**: 実装と同時に単体テストを追加してください。
+- 新規作成したクラス・関数には単体テストを追加
+- 既存コードを変更した場合は該当するテストを更新。ただし既存期待値を実装都合で緩和しない
+- テストファイルの配置: プロジェクトの規約に従う
+- ビルド確認は必須。実装完了後、ビルド（型チェック）を実行し、型エラーがないことを確認
+- テスト実行は必須。ビルド成功後、必ずテストを実行して結果を確認
+- ファイル名・設定キー名などの契約文字列を新規導入する場合は、定数として1箇所で定義すること
+
+**保守変更の追加制約:**
+- 実装前に差分予定を「必須変更」「関連変更」「不要変更」に分類する
+- 必須変更と関連変更だけを実装する
+- 変更ファイル内という理由だけで、作法改善、改名、ファイル移動、hook戻り値変更、コメント削除、テスト期待値変更を行わない
+- 既存構造で要求を満たせる場合は、より一般的な作法へ寄せるためだけの構造変更をしない
+- 実装後に全差分を確認し、不要変更を戻す
+
+**Maintenance Scope出力契約（実装開始時に作成）:**
+```markdown
+# 保守変更スコープ
+
+## タスク
+{タスクの1行要約}
+
+## 必須変更
+| ファイル | 理由 | 要求との対応 |
+|----------|------|--------------|
+| {ファイル} | {理由} | {対応する要求} |
+
+## 関連変更
+| ファイル | 理由 | 必須変更との関係 |
+|----------|------|------------------|
+| {ファイル} | {理由} | {関係} |
+
+## 変更しない既存契約
+| 契約 | 対象 | 守る内容 |
+|------|------|----------|
+| {契約種別} | {対象} | {守る内容} |
+```
+
+**Decisions出力契約（実装完了時、決定がある場合のみ）:**
+```markdown
+# 決定ログ
+
+## 1. {決定内容}
+- **背景**: {なぜ決定が必要だったか}
+- **検討した選択肢**: {選択肢リスト}
+- **理由**: {選んだ理由}
+```
+
+**実装完了前の自己チェック（必須）:**
+
+ビルドとテストを実行する前に、次の手順で Policy の REJECT 基準を自己点検してください。
+
+1. Policy の Source Path を Read ツールで開き、全文を取得する
+2. 各 `##` セクションをすべて列挙する（取捨選択しない）
+3. 列挙した各セクションの REJECT 基準と自分の実装を照合する
+4. 全差分を確認し、要求外の改名、移動、コメント削除、UI文言変更、アクセシビリティ名変更、テスト期待値変更が残っていないか確認する
+
+**必須出力（見出しを含める）**
+## 作業結果
+- {実施内容の要約}
+## 変更内容
+- {必須変更と関連変更の要約}
+## 戻した不要変更
+- {戻した変更。なければ「なし」}
+## ビルド結果
+- {ビルド実行結果}
+## テスト結果
+- {テスト実行コマンドと結果}

package/builtins/ja/facets/instructions/plan-maintenance.md

@@ -0,0 +1,51 @@
+既存フロントエンド機能の保守変更としてタスクを分析し、設計を含めた最小差分の実装方針を立ててください。
+
+**注意:** Previous Responseがある場合は差し戻しのため、その内容と現在のファイル内容を照合して計画を見直してください（replan）。
+
+**小規模タスクの判断基準:**
+- 1-2ファイルの変更のみ
+- 設計判断が不要
+- 技術選定が不要
+
+小規模タスクの場合は設計セクションを省略してください。ただし保守変更では、小規模でも既存契約と不要変更の確認は省略しないでください。
+
+**やること:**
+1. **参照資料の読み込み（必須・最初に実行）**
+   - タスク指示書の「参照資料」セクションに記載されたファイル・ディレクトリを **Read/Glob で実際に開いて内容を確認する**
+   - ディレクトリが指定されている場合は中身を列挙し、該当ファイルを特定してから読む
+   - 参照資料が存在しない・見つからない場合はその旨を報告し、推測で代用しない
+   - **指示書に明記されていない別ファイルを「参照資料の代わり」として使うことは禁止**
+2. タスクの要件を理解する
+   - 参照資料の内容と現在の実装を突き合わせて差分を特定する
+   - **要件ごとに「変更要/不要」を判定する。「不要」の場合は現行コードの該当箇所（ファイル:行）を根拠として示すこと。根拠なしの「既に正しい」は禁止**
+   - **要件は、明示要求とそこから直接導ける暗黙要求に限定する。一般的ベストプラクティスや将来拡張を要件化しない**
+   - **要件を細分化するときは、検証可能にするための分解に留める。細分化から新しい要求へ飛躍しない**
+   - **暗黙要求を置く場合は、その根拠となる明示要求を計画レポートで示す**
+3. コードを調査して不明点を解決する
+4. 現行実装で守るべき既存契約を特定する
+   - 既存構造、型名、hook戻り値、UI文言、アクセシビリティ名、コメント、テスト期待値を確認する
+   - 変更が必要な既存契約がある場合は、理由と影響範囲を計画に明記する
+5. 変更候補を「必須変更」「関連変更」「不要変更」に分類する
+   - 変更ファイル内、近い責務、一般作法という理由だけでは関連変更にしない
+   - 不要変更は Coder に実装させない
+6. ファイル構成・設計パターンを決定する（必要な場合）
+   - 既存構造で要求を満たせる場合は、理想的でなくても既存構造を優先する
+7. 実装アプローチを決める
+   - 実装アプローチがナレッジ・ポリシーの制約に違反しないか照合する
+   - 利用者向け機能の追加や変更がある場合、利用者がその機能へ到達する条件・入口・起動経路を固定する
+8. Coder向けの実装ガイドラインに以下を含めること:
+   - 参照すべき既存実装パターン（ファイル:行）。同種の処理が既にある場合は必ず示す
+   - 変更の影響範囲。特に新しいパラメータを追加する場合、配線が必要な全箇所を列挙する
+   - このタスクで特に注意すべきアンチパターン（該当するものがあれば）
+   - 変更してはいけない既存契約
+   - 不要変更として除外した候補
+
+**必須出力（見出しを含める）**
+## 作業結果
+- {計画の要約}
+## 変更分類
+- {必須変更、関連変更、不要変更の分類}
+## 既存契約
+- {守るべき既存契約}
+## 実装方針
+- {最小差分の方針}

package/builtins/ja/facets/instructions/review-coding.md

@@ -0,0 +1,8 @@
+コード差分をレビューしてください。
+
+手順:
+1. タスクの意図、計画、変更差分、実行証跡を確認する
+2. 実装上のバグ、既存動作のリグレッション、セキュリティリスク、テスト不足を探す
+3. 指摘は現在の差分に起因し、ユーザーが修正すべきものだけにする
+4. 各指摘には場所、影響、修正方針を含める
+5. 根拠のない推測、好みだけの変更、今回の差分と無関係な既存問題は指摘しない

package/builtins/ja/facets/instructions/supervise-maintenance.md

@@ -0,0 +1,110 @@
+実行済みのテスト・ビルド・動作確認の証跡を確認し、保守変更として不要な差分が残っていないかも含めて最終承認を行ってください。
+
+手順:
+1. Knowledge と Policy の Source Path を Read ツールで開き、全文を取得する
+2. それぞれの `##` セクションをすべて列挙する（取捨選択しない）
+3. 列挙した各セクションの判定基準を、変更差分・実行証跡・レポートと照合する
+
+## ステップ固有の追加手順
+
+1. タスク指示書の各要件を 1 つずつ抽出する
+   - 1 つの文に複数の条件や経路が含まれる場合は、検証可能な最小単位まで分解する
+   - 並列表現は原則分解する
+2. 各要件について、実装されたコード（ファイル:行）を特定する
+3. コードが要件を満たしていることを実際に確認する（ファイルを読む、実行済みテストやビルドの証跡を確認する）
+   - 片側のケースだけを確認して複合要件全体を ✅ にしてはいけない
+   - 計画レポートや requirements-review の判断を鵜呑みにせず、要件ごとに独立照合する
+   - 充足していない要件が 1 つでもあれば REJECT する
+4. 保守変更スコープを検証する
+   - 必須変更、関連変更、不要変更の分類が妥当か確認する
+   - コメント、型名、ファイル配置、UI文言、アクセシビリティ名、テスト期待値が要求外で変わっていないか確認する
+   - 一般的な品質改善や作法改善だけが理由の差分が残っていれば REJECT する
+5. 前段レビューの finding を再評価する
+   - finding がコード上成立しない場合は false positive として記録する
+   - finding が成立しても、タスク目的を外れた追加要求や過剰な一般化なら overreach として記録する
+   - false positive / overreach を暗黙のまま流さない
+
+## レポートの優先順位（supervise 固有）
+
+- 要約レポートは一次証跡としては扱わない。一次証跡は、実行結果を記録したレポート、具体的な確認内容を記したレビューレポート、実コードの順で確認する
+- 実行結果を記したレポート内の `ビルド結果` / `テスト結果` は一次証跡として扱ってよい
+- `architecture-review` / `qa-review` / `testing-review` / `security-review` / `requirements-review` では、各レポートの `検証証跡` セクションを優先して確認する
+- `検証証跡` の各項目は、確認対象・確認内容・結果が揃っている場合のみ補助証跡として扱う。いずれかが欠ける場合は、その項目を `未確認` として扱う
+- 証跡同士が矛盾する場合は、`実行結果を記したレポート > 具体的な確認内容を持つレビューレポート > 要約レポート` の優先順位で判断する
+
+**Validation出力契約:**
+```markdown
+# 最終検証結果
+
+## 結果: APPROVE / REJECT
+
+## 要件充足チェック
+
+タスク指示書から要件を抽出し、各要件を実コードで個別に検証する。
+
+| # | 要件（タスク指示書から抽出） | 充足 | 根拠（ファイル:行） |
+|---|---------------------------|------|-------------------|
+| 1 | {要件1} | ✅/❌ | `src/file.ts:42` |
+| 2 | {要件2} | ✅/❌ | `src/file.ts:55` |
+
+- ❌ が1件でもある場合は REJECT 必須
+- 根拠なしの ✅ は無効（実コードで確認すること）
+- 一部ケースしか確認できていない場合は ✅ にしない
+- 計画レポートの判断を鵜呑みにせず、要件ごとに独立照合する
+
+## 保守スコープチェック
+
+| 観点 | 結果 | 根拠 |
+|------|------|------|
+| 必須変更のみか | ✅/❌ | {根拠} |
+| 関連変更の理由が明確か | ✅/❌ | {根拠} |
+| 不要変更が残っていないか | ✅/❌ | {根拠} |
+| コメント削除が要求外で起きていないか | ✅/❌ | {根拠} |
+| 型名・ファイル配置・公開APIが要求外で変わっていないか | ✅/❌ | {根拠} |
+| UI文言・アクセシビリティ名・テスト期待値が要求外で変わっていないか | ✅/❌ | {根拠} |
+
+## 前段 finding の再評価
+
+| finding_id | 前段判定 | 再評価 | 根拠 |
+|------------|----------|--------|------|
+| {id} | new / persists / resolved | 妥当 / false_positive / overreach | `src/file.ts:42`, `reports/plan.md` |
+
+- 前段レビューの結論と最終判定が異なる場合は、必ず根拠を書く
+- false_positive / overreach を判定した場合は、task と plan のどちらに照らして不適切か明記する
+- requirements-review の結論を覆す場合は、その理由を必ず根拠付きで明記する
+
+## 検証サマリー
+| 項目 | 状態 | 確認方法 |
+|------|------|---------|
+| テスト | ✅ / ⚠️ / ❌ | {実行ログ・レポート・CI等の証跡} |
+| ビルド | ✅ / ⚠️ / ❌ | {実行ログ・レポート・CI等の証跡} |
+| 動作確認 | ✅ / ⚠️ / ❌ | {確認した証跡。未確認ならその旨} |
+
+## 成果物
+- 作成: {作成したファイル}
+- 変更: {変更したファイル}
+
+## 未完了項目（REJECTの場合）
+| # | 項目 | 理由 |
+|---|------|------|
+| 1 | {項目} | {理由} |
+```
+
+**Summary出力契約（APPROVEの場合のみ）:**
+```markdown
+# タスク完了サマリー
+
+## タスク
+{元の要求を1-2文で}
+
+## 結果
+完了
+
+## 変更内容
+| 種別 | ファイル | 概要 |
+|------|---------|------|
+| 作成 | `src/file.ts` | 概要説明 |
+
+## 検証証跡
+- {確認したテスト/ビルド/動作確認の証跡}
+```

package/builtins/ja/facets/instructions/team-leader-implement.md

@@ -6,14 +6,18 @@
 
 1. 分解の可否を判断する
    - 変更対象ファイルを特定し、ファイル間の依存関係を確認する
-   - 横断的関心事（共有型・ID・イベント）がある場合は分解せず1パートで実装する
+   - まず並行可能な責務境界を探す
+   - 横断的関心事（共有型・ID・イベント）がある場合も、基盤 part → 消費 part → 検証 part に段階分けできるか検討する
    - 変更ファイル数が少ない場合、リファクタ・リネーム系の場合も1パートで実装する
+   - `parts.length === 1` になる場合も、検証分離や段階分けができないか先に検討する
+   - 「実装と検証」のような巨大な単一 part は避ける
 
 2. 分解する場合: ファイルをレイヤー/モジュール単位でグループ化する
    - 凝集度の高い単位でグループを作る（例: ドメイン層 / インフラ層 / API層）
    - 型・インターフェースの依存がある場合は、依存元と依存先を同じグループにまとめる
    - 1つのファイルを複数のパートに割り当てない
    - テストファイルと実装ファイルは同じパートにまとめる
+   - 実装 part と検証 part を分ける
 
 3. 各パートに排他的なファイル担当を割り当てる
    - 各パートの instruction に以下を必ず明記する：
@@ -24,6 +28,7 @@
    - テスト済みの場合は「既存テストがパスするよう実装する」と明記する
    - 品質ゲート（Quality Gates）を参照し、必要な検証は専用の単独パートとして計画する
    - 並列の実装パートには、全体ビルド・全体テストを重複して実行させない
+   - npm test / npm run test:e2e:mock は各実装 part に重複して持たせない
 
 **制約:**
 - テストやビルドが必要な場合は、他パートの変更が揃った後に、単独の検証パートで実行する

package/builtins/ja/facets/instructions/write-tests-first.md

@@ -24,6 +24,11 @@ Workflow Contextに示されたReport Directory内のファイルのみ参照し
 - レスポンス標準の envelope をリクエスト解釈へ流用した実装を見逃さないテストを含める
 - テストは実装完了後にパスすることを前提に書く（この段階ではビルドエラーやテスト失敗は想定内）
 
+**非実行資産に関する制約:**
+- 説明文、ガイド、README、Markdown ドキュメントなどの本文・章タイトル・構成を固定するテストは作成しない
+- docs-only 変更では、明示的な実行契約がない限りテストを追加しない
+- テストが必要なのは、CLI例・設定例・生成物など、コードの挙動や機械処理と結びつく契約がある場合に限る
+
 **テスト実行について:**
 - テスト作成後、テストを実行して結果を確認する
 - 実装前のためテスト失敗・import エラーは想定内（未実装モジュールの import を含む）

package/builtins/ja/facets/instructions/write-tests-maintenance.md

@@ -0,0 +1,45 @@
+既存挙動を保護しながら、計画に基づいてプロダクションコードの実装前にテストを作成してください。
+Workflow Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。
+
+**重要: プロダクションコードは作成・変更しないでください。テストファイルのみ作成可能です。**
+
+**やること:**
+1. 計画レポートを確認し、要求で変わる挙動と変えてはいけない既存挙動を分ける
+2. 対象モジュールの既存コードと既存テストを確認し、テストパターンを把握する
+3. 既存契約を守る回帰テストが不足している場合は追加する
+4. 計画された機能または修正に対する単体テストを作成する
+5. インテグレーションテストの要否を判断し、必要なら作成する
+   - 3つ以上のモジュールを横断するデータフローがあるか？
+   - 新しいステータス／状態が既存ワークフローに合流するか？
+   - 新しいオプションが呼び出しチェーンを通じて末端まで伝搬するか？
+   - いずれかに該当すればインテグレーションテストを作成する
+
+**テスト作成の方針:**
+- プロジェクトの既存テストパターン（命名規約、ディレクトリ構成、ヘルパー）に従う
+- Given-When-Then 構造で記述する
+- 1テスト1概念。複数の関心事を1テストに混ぜない
+- 正常系・異常系・境界値・エッジケースを網羅する
+- 既存期待値を実装都合に合わせて緩和しない
+- 外部契約がある場合は、契約どおりの入力位置を使ったテストを含める
+  - 例: request body は定義された root shape のまま渡す
+  - 例: query / path parameter は body に流用せず、本来の位置から渡す
+- レスポンス標準の envelope をリクエスト解釈へ流用した実装を見逃さないテストを含める
+- テストは実装完了後にパスすることを前提に書く（この段階ではビルドエラーやテスト失敗は想定内）
+
+**非実行資産に関する制約:**
+- 説明文、ガイド、README、Markdown ドキュメントなどの本文・章タイトル・構成を固定するテストは作成しない
+- docs-only 変更では、明示的な実行契約がない限りテストを追加しない
+- テストが必要なのは、CLI例・設定例・生成物など、コードの挙動や機械処理と結びつく契約がある場合に限る
+
+**テスト実行について:**
+- テスト作成後、テストを実行して結果を確認する
+- 実装前のためテスト失敗・import エラーは想定内（未実装モジュールの import を含む）
+- 既存モジュールの import パスミスなど、実装完了後も解消しないエラーは修正する
+
+**必須出力（見出しを含める）**
+## 作業結果
+- {作成・更新したテストの要約}
+## 保護した既存契約
+- {テストで守った既存挙動}
+## テスト結果
+- {実行した場合はコマンドと結果。未実行の場合は理由}

package/builtins/ja/facets/knowledge/architecture.md

@@ -212,6 +212,7 @@ for (const item of resolvedItems) {
 | REJECT | JSDocが関数名の言い換えだけで情報を追加していない |
 | OK | なぜその実装を選んだかの設計判断を説明している |
 | OK | 一見不自然に見える挙動の理由を説明している |
+| OK | 定数・マジックナンバーの算出根拠や内訳を説明している |
 | 最良 | コメントなしでコード自体が意図を語っている |
 
 ```typescript
@@ -238,6 +239,10 @@ if (status === 'interrupted') {
 // OK - 一見不自然な挙動の理由
 // stay はループを引き起こす可能性があるが、ユーザーが明示的に指定した場合のみ使われる
 return step.name;
+
+// OK - 定数の算出根拠
+// paddingTop + paddingBottom + button height
+const footerHeight = 24 + 12 + 48;
 ```
 
 **状態の直接変更の検出基準**
@@ -374,14 +379,14 @@ function createUser(data: UserData) {
 | エラー握りつぶし | 空の `catch {}`、`rescue nil` |
 | マジックナンバー | 説明なしの `if (status == 3)` |
 
-## TODOコメントの厳格な禁止
+## 未完成コードの検出
 
-「将来やる」は決してやらない。今やらないことは永遠にやらない。
+未完成コードの判定基準はコーディングポリシーに従う。アーキテクチャレビューでは、TODO/FIXME、空実装、スタブが設計上必要な境界・認可・バリデーション・契約更新の代替になっていないかを見る。
 
-TODOコメントは即REJECT。
+Issue番号・外部制約・除去条件のない TODO/FIXME は REJECT。
 
 ```kotlin
-// REJECT - 将来を見越したTODO
+// REJECT - 認可チェックをTODOで先送り
 // TODO: 施設IDによる認可チェックを追加
 fun deleteCustomHoliday(@PathVariable id: String) {
     deleteCustomHolidayInputPort.execute(input)
@@ -398,12 +403,12 @@ fun deleteCustomHoliday(@PathVariable id: String) {
 }
 ```
 
-TODOが許容される唯一のケース:
+TODO/FIXMEが許容されるケース:
 
 | 条件 | 例 | 判定 |
 |------|-----|------|
-| 外部依存で今は実装不可 + Issue化済み | `// TODO(#123): APIキー取得後に実装` | 許容 |
-| 技術的制約で回避不可 + Issue化済み | `// TODO(#456): ライブラリバグ修正待ち` | 許容 |
+| 外部依存で今は実装不可 + Issue化済み + 除去条件あり | `// TODO(#123): APIキー取得後に実装` | 許容 |
+| 技術的制約で回避不可 + Issue化済み + 除去条件あり | `// TODO(#456): ライブラリバグ修正待ち` | 許容 |
 | 「将来実装」「後で追加」 | `// TODO: バリデーション追加` | REJECT |
 | 「時間がないので」 | `// TODO: リファクタリング` | REJECT |
 
@@ -429,7 +434,7 @@ DRY にしないケース:
 
 ## 仕様準拠の検証
 
-変更が、プロジェクトの文書化された仕様に準拠しているか検証する。
+契約変更の整合性はコーディングポリシーに従う。アーキテクチャレビューでは、変更が文書化された仕様、型、スキーマ、設定形式と矛盾していないかを見る。
 
 検証対象:
 
@@ -460,10 +465,10 @@ DRY にしないケース:
 
 ## 呼び出しチェーン検証
 
-新しいパラメータ・フィールドが追加された場合、変更ファイル内だけでなく呼び出し元も検証する。
+契約変更の配線漏れはコーディングポリシーに従う。アーキテクチャレビューでは、新しいパラメータ・フィールドが変更ファイル内だけで完結しておらず、実際の呼び出し元・生成元・読み取り側まで届いているかを見る。
 
 検証手順:
-1. 新しいオプショナルパラメータや interface フィールドを見つけたら、`Grep` で全呼び出し元を検索
+1. 新しいオプショナルパラメータや interface フィールドを見つけたら、全呼び出し元を検索
 2. 全呼び出し元が新しいパラメータを渡しているか確認
 3. フォールバック値（`?? default`）がある場合、フォールバックが使われるケースが意図通りか確認
 
@@ -471,7 +476,7 @@ DRY にしないケース:
 
 | パターン | 問題 | 検出方法 |
 |---------|------|---------|
-| `options.xxx ?? fallback` で全呼び出し元が `xxx` を省略 | 機能が実装されているのに常にフォールバック | grep で呼び出し元を確認 |
+| `options.xxx ?? fallback` で全呼び出し元が `xxx` を省略 | 機能が実装されているのに常にフォールバック | 呼び出し元を確認 |
 | テストがモックで直接値をセット | 実際の呼び出しチェーンを経由しない | テストの構築方法を確認 |
 | `executeXxx()` が内部で使う `options` を引数で受け取らない | 上位から値を渡す口がない | 関数シグネチャを確認 |
 
@@ -493,12 +498,12 @@ export async function executeWorkflow(config, cwd, task, options?) {
 
 | パターン | 問題 | 検出方法 |
 |---------|------|---------|
-| 呼び出し元がTTY必須なのに関数内でTTYチェック | 到達しない分岐が残る | grep で全呼び出し元の前提条件を確認 |
+| 呼び出し元がTTY必須なのに関数内でTTYチェック | 到達しない分岐が残る | 全呼び出し元の前提条件を確認 |
 | 呼び出し元がnullチェック済みなのに再度nullガード | 冗長な防御 | 呼び出し元の制約を追跡 |
 | 呼び出し元が型で制約しているのにランタイムチェック | 型安全を信頼していない | TypeScriptの型制約を確認 |
 
 検証手順:
-1. 防御的な条件分岐（TTYチェック、nullガード等）を見つけたら、grep で全呼び出し元を確認
+1. 防御的な条件分岐（TTYチェック、nullガード等）を見つけたら、全呼び出し元を確認
 2. 全呼び出し元がその条件を既に保証しているなら、防御は不要 → REJECT
 3. 一部の呼び出し元が保証していない場合は、防御を残す
 

package/builtins/ja/facets/knowledge/cqrs-es.md

@@ -205,6 +205,54 @@ data class OrderCancelledEvent(
 - 適切: `ShippingAddressChanged` → 意図が明確
 - 粗すぎ: `OrderModified` → 何が変わったか不明
 
+## Event Evolution
+
+イベントは永続化済みの契約であり、現在のイベント型を変えた場合でも過去イベントを再生できなければならない。旧イベントの読み替えはイベント本体やドメインロジックではなく、イベントストアから復元する境界の upcaster / migration 層で行う。
+
+| 基準 | 判定 |
+|------|------|
+| 永続化済みイベントの型・フィールドを変更したのに変換経路がない | REJECT |
+| 現行イベント型に旧フィールド名の alias や互換用プロパティを残す | REJECT。履歴互換は upcaster に分離 |
+| Aggregate や apply が旧イベント形式を直接解釈する | REJECT。再生前に現行イベントへ変換する |
+| イベントに「変更前の値」を互換目的で追加する | REJECT。イベントは発生後の事実を表す |
+| upcaster が旧 payload を現行イベントの意味へ変換する | OK |
+| 旧 payload から現行イベントへ変換できることをテストしている | OK |
+
+イベント進化で分ける責務:
+
+| 責務 | 置き場所 |
+|------|----------|
+| 現行イベントの意味とフィールド | イベント型 |
+| 旧 payload の読み替え | upcaster / migration 層 |
+| イベント再生による状態復元 | Aggregate の `apply` |
+| 旧イベントから現行イベントへ変換できることの保証 | upcaster テスト |
+
+```kotlin
+// NG - 現行イベント型に旧フィールド互換を混ぜる
+data class OrderAssignedEvent(
+    val orderId: String,
+    @JsonAlias("assigneeId")
+    val assigneeIds: List<String>
+)
+
+// OK - 現行イベント型は現行契約だけを表す
+data class OrderAssignedEvent(
+    val orderId: String,
+    val assigneeIds: List<String>
+)
+```
+
+```kotlin
+// OK - 旧 payload を upcaster で現行 payload へ変換する
+when (eventType) {
+    OrderAssignedEvent::class.java.typeName -> {
+        event.moveTextFieldToArray("assigneeId", "assigneeIds")
+    }
+}
+```
+
+旧イベント型そのものをアプリケーションコードに残すかどうかは、利用フレームワークと運用方針で決める。一般には「旧型を通常のドメインイベントとして扱う」のではなく、「旧 serialized type と payload を upcaster の入力契約としてテストする」方が、現行モデルを汚さずに済む。
+
 ## コマンドハンドラ
 
 | 基準 | 判定 |

package/builtins/ja/facets/knowledge/existing-system.md

@@ -0,0 +1,70 @@
+# 既存システム知識
+
+## 既存システムの契約
+
+既存システムでは、明示的なAPIだけでなく、利用者や開発者が観測している値や構造も契約として機能する。コード上は小さな変更でも、運用中の画面、テスト、レビュー、保守手順に影響する。
+
+| 基準 | 判定 |
+|------|------|
+| 利用者が目にする文言や状態が変わる | 契約変更 |
+| テストが検証している値が変わる | 契約変更 |
+| hook や component の呼び出し方が変わる | 契約変更 |
+| ファイル配置や型名だけが変わる | 保守契約の変更になりうる |
+| 実装内部の閉じた重複を削る | 影響範囲が閉じていれば内部変更 |
+
+## 差分分類
+
+既存システムの変更は、要求との因果関係で分類する。変更対象ファイルに含まれているかどうかではなく、その変更が要求達成に必要かで判断する。
+
+| 分類 | 判断基準 |
+|------|----------|
+| 必須変更 | 要求を満たすために直接必要 |
+| 関連変更 | 必須変更を配線、検証、整合させるために必要 |
+| 不要変更 | なくても要求が満たせる |
+| 危険な不要変更 | なくても要求が満たせ、既存契約も変える |
+
+### 関連変更の境界
+
+関連変更は必須変更との接続理由を説明できる必要がある。近い場所、同じファイル、同じ責務というだけでは関連変更にならない。
+
+| 例 | 分類 |
+|----|------|
+| 新しい引数を追加した関数の呼び出し元更新 | 関連変更 |
+| 永続化先を変えたため古いstoreを削除 | 関連変更 |
+| 触ったcomponentのProps型名を好みで変更 | 不要変更 |
+| ついでにhookの戻り値をprops objectへ変更 | 危険な不要変更 |
+
+## 一般品質基準との衝突
+
+保守作業では、一般的な設計改善やフレームワーク作法が常に優先されるわけではない。既存の構造が理想的でなくても、今回の要求と無関係なら変更しない方が回帰リスクは低い。
+
+| 状況 | 判断 |
+|------|------|
+| コンポーネント分割した方がきれいだが、今回の修正に不要 | 変更しない |
+| Props 型名や配置を一般作法へ寄せたいだけ | 変更しない |
+| 既存構造のままだと要求を満たせない | 最小範囲で変更する |
+| 既存構造が不具合原因そのもの | 理由と影響範囲を明記して変更する |
+
+## コメントとテストの意味
+
+コメントやテストは、過去の制約や意図を保存していることがある。説明に見えるコメントでも、算出根拠、プラットフォーム制約、既知の不具合回避を示す場合は契約に近い役割を持つ。
+
+| 対象 | 扱い |
+|------|------|
+| 算出根拠コメント | 保持する |
+| 制約や回避策のコメント | 保持する |
+| コードと矛盾したコメント | 修正する |
+| 関数名の言い換えだけのコメント | 削除を検討できる |
+| 既存テストの期待値 | 既存契約として扱う |
+
+## 保守変更のリスク
+
+保守変更では、新しいコードの良さより既存挙動の保持が重要になる。設計として良い変更でも、要求外ならレビュー負荷と回帰リスクを増やす。
+
+| 変更 | リスク |
+|------|--------|
+| 改名 | grep、履歴追跡、レビュー範囲が増える |
+| ファイル移動 | 所有境界、import、履歴追跡が変わる |
+| UI契約変更 | 利用者体験、支援技術、テストが変わる |
+| テスト緩和 | 回帰検出力が落ちる |
+| 追加抽象化 | 将来ではなく現在の理解コストが増える |

package/builtins/ja/facets/knowledge/frontend.md

@@ -71,6 +71,18 @@ DataGrid、日付ピッカー、チャート、仮想リストのような外部
 | 代表的な props で実コンポーネントを描画し、画面レベルでクラッシュしないことを確認する | OK |
 | 既存画面の利用パターンやプロジェクト依存バージョンを参照して props 形を決める | OK |
 
+### アクセシビリティ契約
+
+accessible name、role、state は支援技術とテストが参照する UI 契約である。新しい UI 要素には適切なアクセシビリティ属性を追加する一方で、既存要素の契約を変える場合は文言変更と同じく利用者影響のある変更として扱う。
+
+| 基準 | 判定 |
+|------|------|
+| 新しい操作要素に accessible name がない | REJECT |
+| チェック状態、展開状態、無効状態などの状態が支援技術へ公開されていない | 警告 |
+| 既存の accessible name を要求外で変更する | REJECT |
+| 既存の accessible name を保ち、不足していた role/state を追加する | OK |
+| 既存契約を変更する理由と影響範囲が明示されている | OK |
+
 ## コンポーネント設計
 
 1ファイルにベタ書きしない。必ずコンポーネント分割する。
@@ -185,6 +197,19 @@ const Parent = () => {
 | useEffectの依存配列が不適切 | REJECT |
 | 初期取得が不安定な Context/Provider 関数参照に結び付いている | REJECT |
 
+### 正規状態と派生状態
+
+state にはユーザー入力、サーバーデータ、UIの一時状態などの正規状態を保持する。正規状態から計算できる表示値、集計値、選択状態、並び替え結果、グルーピング結果は派生値として扱い、独立した state として保持しない。
+
+| 基準 | 判定 |
+|------|------|
+| ある state から常に計算できる値を別 state として保持している | REJECT |
+| 複数の state フィールド間に常時同期が必要な不変条件がある | REJECT |
+| 表示ラベル、件数、合計、全選択状態、並び替え結果、グルーピング結果を正規 state として保持している | REJECT |
+| API送信、保存、差分判定が正規 state ではなく派生 state に依存している | REJECT |
+| 正規 state だけを保持し、表示・集計・判定は selector、render、useMemo で導出している | OK |
+| 外部契約で必要な派生値を、送信・保存の境界で正規 state から生成している | OK |
+
 状態配置の判断基準:
 
 | 状態の性質 | 推奨配置 |

package/builtins/ja/facets/knowledge/react.md

@@ -120,6 +120,41 @@ custom hook 内の `useState` は呼び出し元ごとに別インスタンス
 | 共有状態が必要な複数コンポーネントで同じ stateful hook を個別に呼ぶ | REJECT |
 | hook が JSX を返す | REJECT |
 
+### Props 型の配置と hook の境界
+
+コンポーネント専用の Props 型は、基本的にそのコンポーネントと同じファイルへ置く。別ファイルの型定義は、複数コンポーネントで共有する契約、外部公開 API、またはドメインモデルとして独立した意味を持つ場合に使う。
+
+| 基準 | 判定 |
+|------|------|
+| 1つのコンポーネント専用 Props を、理由なく `types` ファイルへ切り出す | 警告 |
+| hook から component の Props 型を import するためだけに Props を別ファイルへ移す | REJECT |
+| 複数コンポーネントや公開 API が共有する Props/データ契約を別ファイルへ置く | OK |
+| hook は状態・イベント・派生値を返し、container が component props へ束ねる | OK |
+| hook が component props を返す場合でも、component への型依存を hook に持ち込まない | OK |
+
+```tsx
+// REJECT - hook が特定 component の Props 契約に依存している
+import type { DialogProps } from './Dialog'
+
+export function useDialog(): { dialogProps: DialogProps } {
+  return { dialogProps: { open, onOpenChange } }
+}
+
+// OK - component 専用 Props は component 側に閉じる
+interface DialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}
+
+export function Dialog(props: DialogProps) {
+  return <Modal {...props} />
+}
+
+// OK - hook は UI 状態と操作を返し、呼び出し側で component に渡す
+const dialog = useDialog()
+return <Dialog open={dialog.open} onOpenChange={dialog.setOpen} />
+```
+
 ## exhaustive-deps の扱い
 
 `react-hooks/exhaustive-deps` は無条件で従うものではなく、effect の意味を壊さない範囲で従う。mount-only 初期化で依存を増やすと挙動が壊れる場合は、理由を残して抑制する。