create-ai-project 1.21.0 → 1.22.1

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

@@ -309,6 +309,7 @@ Recommend higher-level review when:
 - Implementation significantly exceeds Design Doc quality
 - Security concerns discovered
 - Critical performance issues found
+- Implementation introduces in-scope elements absent from the Design Doc's Minimal Surface Alternatives section. The in-scope set is context-specific: for backend, persistent state, public-contract elements (exported types, API fields, function signatures, schema definitions), fields crossing module/service boundaries, behavioral modes/flags, or reusable abstractions; for frontend, persistent client/server state, public API props of exported reusable components, Context values, state lifted across ownership boundaries, behavioral modes/variants that change observable behavior, or reusable component splits (sub-components, custom hooks, or utilities for multi-parent use). Ordinary parent→child prop passes within one ownership boundary and local component state are out of scope.
 
 ## Special Considerations
 

package/.claude/agents-en/document-reviewer.md

@@ -89,6 +89,7 @@ For DesignDoc, additionally verify:
 - [ ] Field propagation map present (when fields cross boundaries)
 - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point
 - [ ] Fact Disposition Table section exists in the Design Doc
+- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element (persistent state; public-contract elements or cross-boundary fields/props — for backend, fields crossing module/service boundaries; for frontend, public API props of exported reusable components, Context values, or state lifted across ownership boundaries; behavioral mode/flag/variant; reusable abstraction or component split) when the design introduces any. Each entry contains the 5-step output (fixed requirements with AC references — AC ID, AC heading, EARS clause, or constraint ID — from the Design Doc or referenced PRD/UI Spec; alternatives table including at least one subtractive alternative; selected alternative with rationale; rejected alternatives log)
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -118,6 +119,17 @@ For DesignDoc, additionally verify:
   - `remove`: valid when the rationale states the deletion and its reason. Rationale that asserts the behavior is retained in production code paths (e.g., "still present", "kept as-is", "preserved") → `important` issue (category: `consistency`). Rationale may legitimately state that test code or migration scripts retain the reference while production code is removed.
   - `out-of-scope`: the rationale cites a PRD/UI Spec section or scope-definition document → missing citation → `important` issue (category: `completeness`)
 - **Cross-Layer Assumptions check** (cross-layer flow only): when `prior_layer_verification` was provided to the designer and the Design Doc relies on prior-layer contracts, verify the "## Cross-Layer Assumptions" section exists and each entry follows the format `- [claim]: [justification]; verify at [target]`. Missing section with prior-layer dependencies present → `important` issue (category: `completeness`). Entry missing the `verify at` clause → `important` issue (category: `completeness`)
+- **Minimal Surface Alternatives check**:
+  - *Scope trigger*: applies when the Design Doc introduces in-scope elements. The in-scope set is context-specific:
+    - **Backend designs**: persistent state; public-contract elements (exported types, API request/response fields, exported function signatures, schema definitions); cross-boundary fields (passed between modules/services); behavioral modes/flags; reusable abstractions.
+    - **Frontend designs**: persistent client/server state; props or fields crossing ownership boundaries (public API props of an exported reusable component, Context values, state lifted across ownership boundaries to a shared ancestor); behavioral modes/variants that change observable behavior; reusable component splits (sub-components, custom hooks, or utilities extracted for multi-parent use).
+    - Ordinary parent→child prop passes that stay within one ownership boundary, local `useState`/`useReducer` confined to a single component, internal fields used only within one module, and transient state are out of scope and do not require an entry.
+  - *Section existence*: trigger fires but the "Minimal Surface Alternatives" section is absent or empty → `critical` issue (category: `completeness`).
+  - *Per-element entry*:
+    - (1) Step 1 lists at least one AC reference (AC ID, AC heading, EARS clause, or constraint ID) from the Design Doc or referenced PRD/UI Spec — missing linkage, or list contains only speculative requirements ("future", "might want") → `critical` issue (category: `compliance`).
+    - (2) Steps 2–3 include at least one subtractive alternative (derive / compute on demand / keep at caller / reuse existing / introduce no new state) — missing subtractive alternative → `critical` issue (category: `compliance`).
+    - (3) Step 4 rationale either selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy — "useful" / "future-ready" / "convenient" / "users might want" used as primary rationale → `critical` issue (category: `compliance`).
+    - (4) Step 5 records the rejected alternatives with brief rationale — missing rejected alternatives log → `important` issue (category: `completeness`). Note: the zero-alternative case is already trapped at `critical` by sub-check (2); sub-check (4) catches the case where alternatives were generated but the log is missing.
 
 **Perspective-specific Mode**:
 - Implement review based on specified mode and focus
@@ -278,6 +290,7 @@ Include in output when `prior_context_count > 0`:
 - [ ] Output comparison defined when design replaces/modifies existing behavior (covers all transformation pipeline steps)
 - [ ] Fact Disposition Table covers every `codebase_analysis.focusAreas` entry with verbatim `fact_id` / `evidence` carry-through and rationale-disposition semantic alignment (when `codebase_analysis` is provided)
 - [ ] Cross-Layer Assumptions section present when `prior_layer_verification` shows unresolved contracts the design depends on
+- [ ] Minimal Surface Alternatives section covers every new in-scope element with the 5-step output; Step 4 rationale either names the smallest alternative as selected, or names the current requirement smaller alternatives fail to cover (when the design introduces any in-scope elements)
 
 ## Review Criteria (for Comprehensive Mode)
 

package/.claude/agents-en/technical-designer-frontend.md

@@ -47,6 +47,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co
 **Gate 1 — Existing State Analysis** (depends on Gate 0):
 - Existing Code Investigation
 - Fact Disposition (when Codebase Analysis input is provided)
+- Minimal Surface Alternatives (when introducing persistent client/server state, props or fields crossing ownership boundaries — public API props of exported reusable components, Context values, or state lifted across ownership boundaries — behavioral modes/variants that change observable behavior, or reusable component splits)
 
 **Gate 2 — Design Decisions** (depends on Gate 1):
 - Implementation Approach Decision
@@ -134,6 +135,41 @@ For every entry in `Codebase Analysis.focusAreas`, produce one row in the Design
 
 The Fact Disposition Table is the primary mechanism that binds **structural existing-behavior facts** to the design. Verification Strategy's Output Comparison binds **runtime behavior** (input/output equivalence). Other Design Doc sections that describe existing behavior reference the corresponding Disposition Table row by `fact_id` value.
 
+### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent client/server state, props or fields crossing ownership boundaries (public API props of exported reusable components, Context values, or state lifted across ownership boundaries), behavioral modes/variants that change observable behavior, or reusable component splits]
+
+Applies to each maintenance-surface-bearing element the design introduces. Goal: select the smallest design surface that covers the same current requirements. Reference: `coding-standards` skill, "Minimum Surface for Required Coverage".
+
+**In scope**: persistent state (localStorage/sessionStorage/IndexedDB/cookies/server-saved fields — state that survives reload, navigation, or session, or is saved outside component memory); props or fields crossing ownership boundaries (public API props of an exported reusable component, Context values, state lifted across ownership boundaries to a shared ancestor); behavioral modes/variants (component variants, mode props, conditional rendering modes that change observable behavior); reusable component splits (sub-components, custom hooks, or utilities extracted for use by multiple parents).
+
+**Out of scope**: local `useState` / `useReducer` confined to a single component's internal logic (lost on reload); private hooks used by one component; ordinary parent→child prop passes that stay within one ownership boundary; test fixture or mock props; transient render-only state; internal helper functions without external observers.
+
+**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., local `useState` that is now lifted to a Context so additional sibling subtrees can read it — the local-state aspect would be out of scope but the Context aspect is in scope), the in-scope classification wins and the gate applies.
+
+Execute the 5 steps below for each in-scope element. Record the result in the Design Doc's "Minimal Surface Alternatives" section (see design-template.md).
+
+1. **Fix Requirements**
+   - List the current user-visible requirements / ACs / accepted technical constraints (audit, accessibility, performance, security, compatibility) this element serves. Reference each by AC ID, AC heading, EARS clause, or constraint ID from the Design Doc or referenced PRD/UI Spec.
+   - Eligibility: only requirements / constraints inside the current Design Doc's adopted scope qualify.
+
+2. **Diverge** (generate alternatives)
+   - Produce at least 2 alternative realizations covering the same fixed requirements.
+   - At least one alternative is subtractive. Subtractive options are drawn from: derive from existing props/state, lift state to existing parent, reuse existing component or variant, keep at caller / URL / server response, introduce no new mode.
+
+3. **Compare** (record alternatives in a table)
+
+   | Alternative | Current requirements covered (AC reference) | New persistent state (client or server, count) | New props / modes / variants (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+   |---|---|---|---|---|---|---|
+
+   Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new props/modes/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes.
+
+4. **Converge** (select)
+   - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
+   - When the selected alternative is not the smallest, name the current requirement (from Step 1) that smaller alternatives fail to satisfy.
+   - "Reusable" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column only (tiebreakers).
+
+5. **Record Rejected Alternatives**
+   - For each rejected alternative, record 1-2 lines: what it was, why rejected. Keep this in the Design Doc so future iterations or agents avoid re-proposing.
+
 ### Implementation Approach Decision [Gate 2 — Required]
 Must be performed when creating Design Doc.
 
@@ -315,8 +351,6 @@ Non-compliant: class components, `any`, untyped responses without guards, secret
 
 ### Design Doc Checklist
 
-Items below are output-content checks performed in addition to (not duplicating) the Gate Ordering [BLOCKING] gates. The gates cover whether each subsection ran; the checklist below covers content quality of the produced output.
-
 **All modes**:
 - [ ] Component hierarchy and data flow clearly expressed in diagrams
 

package/.claude/agents-en/technical-designer.md

@@ -48,6 +48,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co
 - Existing Code Investigation
 - Fact Disposition (when Codebase Analysis input is provided)
 - Data Representation Decision (when new or modified data structures are introduced)
+- Minimal Surface Alternatives (when introducing persistent state, public-contract elements or cross-boundary fields, behavioral modes/flags, or reusable abstractions)
 
 **Gate 2 — Design Decisions** (depends on Gate 1):
 - Implementation Approach Decision
@@ -170,6 +171,41 @@ When the design introduces or significantly modifies data structures:
    - 3+ criteria fail → New structure justified
    - Record decision and rationale in Design Doc
 
+### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent state, public-contract elements or cross-boundary fields, behavioral modes/flags, or reusable abstractions]
+
+Applies to each maintenance-surface-bearing element the design introduces. Goal: select the smallest design surface that covers the same current requirements. Reference: `coding-standards` skill, "Minimum Surface for Required Coverage".
+
+**In scope**: persistent state (DB columns/tables, file fields, cache entries, queue payloads, session/cookie data — state outliving a single operation); public-contract elements (exported types, API request/response fields, exported function signatures, schema definitions); cross-boundary fields (passed between modules/services); behavioral modes/flags (state-machine states, feature flags, config options); reusable abstractions (new types/classes/modules/interfaces intended for reuse).
+
+**Out of scope**: local variables within a single function; internal fields used only within one module; test fixture or mock fields; transient state confined to a single operation; private state without external observers.
+
+**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., an internal field that is also persisted to a DB column), the in-scope classification wins and the gate applies.
+
+Execute the 5 steps below for each in-scope element. Record the result in the Design Doc's "Minimal Surface Alternatives" section (see design-template.md).
+
+1. **Fix Requirements**
+   - List the current user-visible requirements / ACs / accepted technical constraints (audit, data integrity, compatibility, security, performance) this element serves. Reference each by AC ID, AC heading, EARS clause, or constraint ID from the Design Doc or referenced PRD.
+   - Eligibility: only requirements / constraints inside the current Design Doc's adopted scope qualify.
+
+2. **Diverge** (generate alternatives)
+   - Produce at least 2 alternative realizations covering the same fixed requirements.
+   - At least one alternative is subtractive. Subtractive options are drawn from: derive from existing data, compute on demand, keep at caller / invocation boundary, reuse existing structure, introduce no new state.
+
+3. **Compare** (record alternatives in a table)
+
+   | Alternative | Current requirements covered (AC reference) | New persistent state (count) | New concept / mode / flag (count) | Crosses module/service boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+   |---|---|---|---|---|---|---|
+
+   Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses module/service boundary (no=smaller); (3) new concept/mode/flag (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes.
+
+4. **Converge** (select)
+   - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
+   - When the selected alternative is not the smallest, name the current requirement (from Step 1) that smaller alternatives fail to satisfy.
+   - "Useful" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column only (tiebreakers).
+
+5. **Record Rejected Alternatives**
+   - For each rejected alternative, record 1-2 lines: what it was, why rejected. Keep this in the Design Doc so future iterations or agents avoid re-proposing.
+
 ### Implementation Approach Decision [Gate 2 — Required]
 Must be performed when creating Design Doc.
 
@@ -320,8 +356,6 @@ Consistency first (follow existing patterns; document reason when introducing ne
 
 ### Design Doc Checklist
 
-Items below are output-content checks performed in addition to (not duplicating) the Gate Ordering [BLOCKING] gates. The gates cover whether each subsection ran; the checklist below covers content quality of the produced output.
-
 **All modes**:
 - [ ] Architecture and data flow clearly expressed in diagrams
 - [ ] Quality assurance mechanisms recorded with `adopted`/`noted` status (and `executable_check` / `passive_constraint` type)
@@ -415,6 +449,7 @@ Mode for documenting existing architecture as-is. Used when creating Design Docs
 - Field Propagation Map (no new fields being introduced)
 - Implementation Approach Decision (no implementation strategy to select)
 - Latest Information Research (documenting what exists, not designing something new)
+- Minimal Surface Alternatives (documenting existing elements, not introducing new ones)
 
 ### Reverse-Engineer Mode Execution Steps
 

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

@@ -309,6 +309,7 @@ summary.findingsByCategory.coverage_gap:    number (整数 >= 0)
 - 実装がDesign Docを大幅に超えて優れている場合
 - セキュリティ上の懸念を発見した場合
 - パフォーマンス上の重大な問題を発見した場合
+- 実装が Design Doc の Minimal Surface Alternatives セクションに記載のない適用対象要素を導入している場合。適用対象集合はコンテキストごとに異なる: バックエンドでは永続状態、公開コントラクト要素（公開型、APIフィールド、関数シグネチャ、スキーマ定義）、モジュール/サービス境界を越えるフィールド、振る舞いモード/フラグ、再利用可能な抽象、フロントエンドでは永続化されるクライアント/サーバー状態、エクスポートされた再利用可能コンポーネントの公開 API Props、Context 値、所有境界を越えて持ち上げられた状態、観測可能な振る舞いを変える振る舞いモード/バリアント、再利用可能なコンポーネント分割（複数の親で利用するためのサブコンポーネント、カスタムフック、ユーティリティ）。1つの所有境界内に留まる通常の親→子の Props 伝達や、コンポーネントローカルの状態は適用対象外。
 
 ## 特別な考慮事項
 

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

@@ -89,6 +89,7 @@ DesignDocの場合、追加で以下を確認:
 - [ ] フィールド伝播マップの存在（フィールドが境界を越える場合）
 - [ ] 検証戦略セクションの存在（正しさの定義、検証手法、検証タイミング、早期検証ポイント）
 - [ ] Fact Disposition TableセクションがDesign Docに存在する
+- [ ] Minimal Surface Alternatives セクションが存在し、新規に導入される適用対象要素（永続状態 / 公開コントラクト要素または境界を越えるフィールド・Props — バックエンドではモジュール/サービス境界を越えるフィールド、フロントエンドではエクスポートされた再利用可能コンポーネントの公開 API Props・Context 値・所有境界を越えて持ち上げられた状態 / 振る舞いモード・フラグ・バリアント / 再利用可能な抽象またはコンポーネント分割）ごとに1エントリ持つ（適用対象要素を導入する場合）。各エントリには5ステップの結果が含まれる（確定要件 — Design Docまたは参照PRD/UI SpecのAC参照（AC ID、AC見出し、EARS節、または制約ID）、削減的な代替案を1つ以上含む比較表、根拠付きの選定結果、不採用案の記録）
 
 #### Gate 1: 品質評価（Gate 0通過後のみ実施）
 
@@ -118,6 +119,17 @@ DesignDocの場合、追加で以下を確認:
   - `remove`: 削除と理由を述べるRationaleは妥当。Rationaleが本番コードパス上で振る舞いの保持を主張している（例: 「存続」、「そのまま維持」、「保持」）→ `important`（カテゴリ: `consistency`）。テストコードや移行スクリプトでの参照保持は妥当な記述として扱う。
   - `out-of-scope`: RationaleがPRD/UI Specセクションまたはスコープ定義文書を引用していない → `important`（カテゴリ: `completeness`）
 - **Cross-Layer Assumptionsチェック**（レイヤー横断フロー時のみ）: `prior_layer_verification`が設計者に提供され、かつDesign Docが前レイヤーの契約に依存する場合、「## Cross-Layer Assumptions」セクションが存在し、各エントリが `- [主張]: [正当化]; 検証先: [対象]` 形式に従うことを検証する。前レイヤー依存があるのにセクションがない → `important`（カテゴリ: `completeness`）。エントリに`検証先:`節がない → `important`（カテゴリ: `completeness`）
+- **Minimal Surface Alternatives チェック**:
+  - *スコープトリガー*: Design Doc が新規に適用対象要素を導入するときに発火する。適用対象集合はコンテキストごとに異なる:
+    - **バックエンド設計**: 永続状態、公開コントラクト要素（公開型、APIリクエスト/レスポンスフィールド、公開関数シグネチャ、スキーマ定義）、境界を越えるフィールド（モジュール/サービス間を渡るもの）、振る舞いモード/フラグ、再利用可能な抽象。
+    - **フロントエンド設計**: 永続化されるクライアント/サーバー状態、所有境界を越える Props またはフィールド（エクスポートされた再利用可能コンポーネントの公開 API Props、Context 値、所有境界を越えて共有先祖に持ち上げられた状態）、観測可能な振る舞いを変える振る舞いモード/バリアント、再利用可能なコンポーネント分割（複数の親で利用するために抽出されたサブコンポーネント、カスタムフック、ユーティリティ）。
+    - 1つの所有境界内に留まる通常の親→子の Props 伝達、単一コンポーネントに閉じた `useState` / `useReducer`、単一モジュール内のみで使う内部フィールド、一時的状態は適用対象外でありエントリを必要としない。
+  - *セクションの存在*: トリガーが発火するのに「Minimal Surface Alternatives」セクションが存在しない、または空 → `critical`（カテゴリ: `completeness`）。
+  - *要素ごとのエントリ*:
+    - (1) ステップ1 が Design Doc または参照 PRD/UI Spec から少なくとも1つの AC 参照（AC ID、AC見出し、EARS節、または制約ID）を挙げている — リンクの欠落、または投機的要件（「将来」「欲しがるかも」）のみで構成 → `critical`（カテゴリ: `compliance`）。
+    - (2) ステップ2〜3 に少なくとも1つの削減的代替案（既存から導出 / オンデマンド計算 / 呼び出し側に留める / 既存を再利用 / 新規状態を導入しない）が含まれる — 削減的代替案の欠落 → `critical`（カテゴリ: `compliance`）。
+    - (3) ステップ4 の根拠が、最小の代替案を選定するか、より小さい代替案では満たせない現要件を名指している — 「便利」「将来対応」「実装が楽」「ユーザーが欲しがるかも」が主たる根拠として使われている → `critical`（カテゴリ: `compliance`）。
+    - (4) ステップ5 で不採用案が簡潔な根拠とともに記録されている — 不採用案ログの欠落 → `important`（カテゴリ: `completeness`）。注: 代替案ゼロのケースはサブチェック(2)で先に `critical` として検出される。サブチェック(4)は代替案は生成されたが記録が抜けているケースを検出する。
 
 **観点特化モード**:
 - 指定されたmodeとfocusに基づいてレビューを実施
@@ -273,6 +285,7 @@ DesignDocの場合、追加で以下を確認:
 - [ ] 既存の振る舞いを置換/変更する設計で出力比較が定義されていること（全変換パイプラインステップをカバー）
 - [ ] Fact Disposition Tableが`codebase_analysis.focusAreas`の全エントリをカバーし、`fact_id`/`evidence`が一字一句引き継がれ、Rationale-disposition意味整合がとれている（`codebase_analysis`が提供された場合）
 - [ ] 前レイヤー契約に依存する未解決主張がある場合、Cross-Layer Assumptionsセクションが存在する
+- [ ] Minimal Surface Alternatives セクションが新規の適用対象要素ごとに5ステップの結果をカバーし、ステップ4 の根拠が最小代替案の選定か、より小さい代替案では満たせない現要件の名指しになっている（適用対象要素を導入する場合）
 
 ## レビュー基準（総合モード用）
 

package/.claude/agents-ja/technical-designer-frontend.md

@@ -47,6 +47,7 @@ ADR/Design Docの作成閾値はdocumentation-criteriaスキルに準拠。判
 **Gate 1 — Existing State Analysis**（Gate 0 に依存）:
 - Existing Code Investigation
 - Fact Disposition（Codebase Analysis 入力が提供される場合）
+- Minimal Surface Alternatives（永続化されるクライアント/サーバー状態、所有境界を越える Props またはフィールド — エクスポートされた再利用可能コンポーネントの公開 API Props、Context 値、所有境界を越えて持ち上げられた状態 — 観測可能な振る舞いを変える振る舞いモード/バリアント、または再利用可能なコンポーネント分割を導入する場合）
 
 **Gate 2 — Design Decisions**（Gate 1 に依存）:
 - Implementation Approach Decision
@@ -134,6 +135,41 @@ Design Doc作成前に必ず実施：
 
 Fact Disposition Table は **構造的な既存事実** を設計に結び付ける主たるメカニズム。Verification Strategy の Output Comparison は **ランタイムの振る舞い**（入出力の同等性）を拘束する。Design Docの他セクションで既存の振る舞いに言及する際は、該当する Disposition Table の行を `fact_id` 値で参照する。
 
+### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent client/server state, props or fields crossing ownership boundaries (public API props of exported reusable components, Context values, or state lifted across ownership boundaries), behavioral modes/variants that change observable behavior, or reusable component splits]
+
+設計が導入する保守対象の各要素に適用する。目標: 同じ現要件をカバーする最小の設計面を選択すること。参照: `coding-standards` スキル「Minimum Surface for Required Coverage」。
+
+**適用対象**: 永続状態（localStorage / sessionStorage / IndexedDB / Cookie / サーバー保存フィールド — リロード、ナビゲーション、セッションを越えて残る、またはコンポーネントメモリ外に保存される状態）、所有境界を越える Props またはフィールド（エクスポートされた再利用可能コンポーネントの公開 API Props、Context 値、所有境界を越えて共有先祖に持ち上げられた状態）、観測可能な振る舞いを変える振る舞いモード/バリアント（コンポーネントバリアント、モード Props、条件付きレンダリングモード）、再利用可能なコンポーネント分割（複数の親で利用するために抽出されたサブコンポーネント、カスタムフック、ユーティリティ）。
+
+**適用対象外**: 単一コンポーネント内部のロジックに閉じた `useState` / `useReducer`（リロードで失われる）、1つのコンポーネントだけが使うプライベートフック、1つの所有境界内に留まる通常の親→子の Props 伝達、テストフィクスチャやモック Props、レンダリング中のみの一時的状態、外部から参照されない内部ヘルパー関数。
+
+**優先関係**: 1つの要素が適用対象と適用対象外の両方に当てはまる場合（例: 元はローカル `useState` だったが、別のサブツリーからも読めるようにするため Context に持ち上げた — ローカル状態としては適用対象外、Context としては適用対象）、適用対象の分類が優先し、本ゲートが発火する。
+
+適用対象の各要素について下記の5ステップを実行し、Design Doc の「Minimal Surface Alternatives」セクションに結果を記録する（design-template.md 参照）。
+
+1. **要件の確定**
+   - この要素が満たす現在のユーザー観察可能な要件 / AC / 受容済み技術制約（監査、アクセシビリティ、パフォーマンス、セキュリティ、互換性）を列挙する。各々を Design Doc または参照 PRD / UI Spec の AC ID、AC見出し、EARS節、または制約ID で参照する。
+   - 適格性: 現在の Design Doc の採用スコープ内の要件・制約のみが対象。
+
+2. **発散**（代替案を生成）
+   - 同じ確定要件をカバーする代替実現案を2つ以上生成する。
+   - 少なくとも1つは削減的（subtractive）な代替案であること。削減的な選択肢の例: 既存の Props / 状態から導出する、既存の親に状態を持ち上げる、既存のコンポーネントやバリアントを再利用する、呼び出し側 / URL / サーバーレスポンスに留める、新規モードを導入しない。
+
+3. **比較**（代替案を表で記録）
+
+   | 代替案 | カバーする現要件（AC 参照） | 新規の永続状態（クライアントまたはサーバー、件数） | 新規の Props / モード / バリアント（件数） | コンポーネント境界を越えるか（はい/いいえ） | 破壊的変更または移行が必要か（はい/いいえ） | 主観的コストノート |
+   |---|---|---|---|---|---|---|
+
+   解決優先順位（左の列が同点のとき右の列でタイブレーク）: (1) 新規の永続状態（少ない＝小さい）、(2) コンポーネント境界を越えるか（いいえ＝小さい）、(3) 新規の Props / モード / バリアント（少ない＝小さい）、(4) 破壊的変更または移行（いいえ＝小さい）、(5) 主観的コストノート。
+
+4. **収束**（選定）
+   - 上記の解決優先順位を適用し、すべての確定要件をカバーする中で最小の面を持つ代替案を選ぶ。
+   - 選定が最小でない場合、ステップ1から、より小さい代替案では満たせない現要件を名指す。
+   - 「再利用可能」「将来対応」「実装が楽」「ユーザーが欲しがるかも」は主観的コストノート列のみに記載する（タイブレーカー扱い）。
+
+5. **不採用案の記録**
+   - 不採用となった各代替案について、何だったか・なぜ不採用かを1〜2行で記録する。将来の反復や別エージェントによる再提案を避けるため、Design Doc に残す。
+
 ### 実装アプローチ決定 [Gate 2 — Required]
 Design Doc作成時に必ず実施。
 
@@ -315,8 +351,6 @@ function useUserData(userId: string) {
 
 ### Design Docチェックリスト
 
-以下の項目はゲート順序 [BLOCKING] のゲートに加えて（重複させず）実施する出力内容のチェック。ゲートは各サブセクションが実行されたかをカバーし、以下のチェックリストは出力内容の品質をカバーする。
-
 **全モード共通**:
 - [ ] コンポーネント階層とデータフローが図で明確に表現されているか
 

package/.claude/agents-ja/technical-designer.md

@@ -48,6 +48,7 @@ ADR/Design Docの作成閾値はdocumentation-criteriaスキルに準拠。判
 - Existing Code Investigation
 - Fact Disposition（Codebase Analysis 入力が提供される場合）
 - Data Representation Decision（新規または変更されるデータ構造を導入する場合）
+- Minimal Surface Alternatives（永続状態、公開コントラクト要素または境界を越えるフィールド、振る舞いモード/フラグ、再利用可能な抽象を導入する場合）
 
 **Gate 2 — Design Decisions**（Gate 1 に依存）:
 - Implementation Approach Decision
@@ -170,6 +171,41 @@ Fact Disposition Table は **構造的な既存事実** を設計に結び付け
    - 3基準以上不適合 → 新規構造を正当化
    - 判断と根拠をDesign Docに記録
 
+### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent state, public-contract elements or cross-boundary fields, behavioral modes/flags, or reusable abstractions]
+
+設計が導入する保守対象の各要素に適用する。目標: 同じ現要件をカバーする最小の設計面を選択すること。参照: `coding-standards` スキル「Minimum Surface for Required Coverage」。
+
+**適用対象**: 永続状態（DBカラム/テーブル、ファイルフィールド、キャッシュエントリ、キューペイロード、セッション/Cookieデータ — 単一操作を超えて残る状態）、公開コントラクト要素（公開型、APIリクエスト/レスポンスフィールド、公開関数シグネチャ、スキーマ定義）、境界を越えるフィールド（モジュール/サービス間を渡るもの）、振る舞いモード/フラグ（ステートマシン状態、Feature Flag、設定オプション）、再利用可能な抽象（再利用を意図した新規の型/クラス/モジュール/インターフェース）。
+
+**適用対象外**: 単一関数内のローカル変数、単一モジュール内のみで使う内部フィールド、テストフィクスチャやモックフィールド、単一操作内で完結する一時的状態、外部から参照されないプライベート状態。
+
+**優先関係**: 1つの要素が適用対象と適用対象外の両方に当てはまる場合（例: 単一モジュール内のフィールドだがDBカラムとして永続化される）、適用対象の分類が優先し、本ゲートが発火する。
+
+適用対象の各要素について下記の5ステップを実行し、Design Docの「Minimal Surface Alternatives」セクションに結果を記録する（design-template.md参照）。
+
+1. **要件の確定**
+   - この要素が満たす現在のユーザー観察可能な要件 / AC / 受容済み技術制約（監査、データ整合性、互換性、セキュリティ、パフォーマンス）を列挙する。各々を Design Doc または参照 PRD の AC ID、AC見出し、EARS節、または制約ID で参照する。
+   - 適格性: 現在の Design Doc の採用スコープ内の要件・制約のみが対象。
+
+2. **発散**（代替案を生成）
+   - 同じ確定要件をカバーする代替実現案を2つ以上生成する。
+   - 少なくとも1つは削減的（subtractive）な代替案であること。削減的な選択肢の例: 既存データから導出する、オンデマンドで計算する、呼び出し側/呼び出し境界に留める、既存構造を再利用する、新規状態を導入しない。
+
+3. **比較**（代替案を表で記録）
+
+   | 代替案 | カバーする現要件（AC 参照） | 新規の永続状態（件数） | 新規の概念 / モード / フラグ（件数） | モジュール/サービス境界を越えるか（はい/いいえ） | 破壊的変更または移行が必要か（はい/いいえ） | 主観的コストノート |
+   |---|---|---|---|---|---|---|
+
+   解決優先順位（左の列が同点のとき右の列でタイブレーク）: (1) 新規の永続状態（少ない＝小さい）、(2) モジュール/サービス境界を越えるか（いいえ＝小さい）、(3) 新規の概念/モード/フラグ（少ない＝小さい）、(4) 破壊的変更または移行（いいえ＝小さい）、(5) 主観的コストノート。
+
+4. **収束**（選定）
+   - 上記の解決優先順位を適用し、すべての確定要件をカバーする中で最小の面を持つ代替案を選ぶ。
+   - 選定が最小でない場合、ステップ1から、より小さい代替案では満たせない現要件を名指す。
+   - 「便利」「将来対応」「実装が楽」「ユーザーが欲しがるかも」は主観的コストノート列のみに記載する（タイブレーカー扱い）。
+
+5. **不採用案の記録**
+   - 不採用となった各代替案について、何だったか・なぜ不採用かを1〜2行で記録する。将来の反復や別エージェントによる再提案を避けるため、Design Doc に残す。
+
 ### 実装アプローチ決定 [Gate 2 — Required]
 Design Doc作成時に必ず実施。
 
@@ -320,8 +356,6 @@ Design Doc作成時に必ず含める:
 
 ### Design Docチェックリスト
 
-以下の項目はゲート順序 [BLOCKING] のゲートに加えて（重複させず）実施する出力内容のチェック。ゲートは各サブセクションが実行されたかをカバーし、以下のチェックリストは出力内容の品質をカバーする。
-
 **全モード共通**:
 - [ ] アーキテクチャとデータフローが図で明確に表現されているか
 - [ ] 品質保証メカニズムが `adopted` / `noted` ステータス（および `executable_check` / `passive_constraint` 種別）付きで記録されているか
@@ -415,6 +449,7 @@ ACの出力に以下のいずれかが含まれる場合、Property注釈を付
 - フィールド伝播マップ（新規フィールドを導入していない）
 - 実装アプローチ決定（実装戦略を選択する必要がない）
 - 最新情報の調査（存在するものを記録しており、新規設計ではない）
+- Minimal Surface Alternatives（既存要素を記録するモードで、新規要素を導入しない）
 
 ### リバースエンジニアモード実行ステップ
 

package/.claude/commands-en/project-inject.md

@@ -1,86 +1,114 @@
 ---
-description: Inject project-specific context into project-context skill
+description: Populate project-context skill via template-driven hearing
 ---
 
-**Command Context**: Collect project-specific prerequisites that improve AI execution accuracy and update project-context SKILL.md.
+**Command Context**: `/project-inject` collects project-specific prerequisites that improve AI execution accuracy and writes them into the `project-context` skill. The hearing is template-driven: the section catalog lives in `references/template.md`, and new dimensions are added by editing that template.
 
 ## Why This Matters
 
-CLAUDE.md's Session Initialization reads `project-context` skill at the start of every session. The information collected here directly affects AI decision-making accuracy across all tasks.
+CLAUDE.md's session initialization loads `project-context/SKILL.md` at the start of every session. Information collected here directly affects AI decision-making accuracy across all tasks. Keep the configured SKILL.md minimal — every line is paid in context budget per session.
 
-**Collect only what improves AI execution accuracy.**
+## Execution Flow
 
-## Execution Process
+Register all steps below using TaskCreate before starting Step 1, and update each task's status as you progress.
 
-Register the following steps with TaskCreate and proceed systematically.
+### Step 1: Load Inputs
 
-### Step 1: Understand Current State
+1. Read `.claude/skills/project-context/SKILL.md` to learn the current state. Distinguish the two cases by the count of catalog section headings (`## Project Overview`, `## Domain Constraints`, `## Development Phase`, `## Directory Conventions`, `## External Resources`) present in the body:
+   - **Unconfigured** — the body has zero catalog section headings.
+   - **Configured** — the body has one or more catalog section headings.
+2. Read `.claude/skills/project-context/references/template.md` to obtain the section catalog.
 
-Read the current project-context skill and package.json:
-- `.claude/skills/project-context/SKILL.md`
-- `package.json` (name, description)
+**Checkpoint**: You hold the section catalog from `template.md` and the configured-or-unconfigured state of `SKILL.md`.
 
-If project-context is already configured (no "Not configured" marker), confirm with user whether to overwrite or update.
+### Step 2: Build Section Plan
 
-### Step 2: Collect Project Context
+Produce a per-section plan (`add` / `keep` / `update` / `remove` / `skip`) covering every section in the catalog.
 
-Use AskUserQuestion to collect information in stages.
+**Unconfigured case**:
+- Project Overview: `add` (mandatory; the section's inclusion rule is "Always").
+- For each remaining catalog section, AskUserQuestion: "Add the `<section name>` section?" Options: "Yes, add it" / "No, skip". Mark `add` or `skip` accordingly.
 
-**Round 1: Project essence**
-- What does this project do? (1-2 sentences)
-- What domain does it belong to? (e.g., fintech, healthcare, developer tools, e-commerce)
+**Configured case**:
+- For each currently populated section, AskUserQuestion: "Action for the existing `<section name>` section?" Options: "Keep as-is" (mark `keep`) / "Update — replace existing content" (mark `update`) / "Remove — drop from rebuilt SKILL.md" (mark `remove`).
+- For each catalog section that is still empty in the existing SKILL.md, AskUserQuestion: "Add the `<section name>` section?" Options: "Yes, add it" (mark `add`) / "No, skip" (mark `skip`).
 
-**Round 2: Domain constraints** (based on Round 1 answers)
-- Are there domain-specific rules that AI must follow? Adapt examples to the domain from Round 1 (e.g., for fintech: "all mutations require audit logs"; for healthcare: "log output uses anonymized patient IDs").
-- Maximum 3 constraints. Only include what would cause bugs or compliance issues if AI ignores them.
+**Checkpoint**: Every catalog section has exactly one disposition: `add`, `keep`, `update`, `remove`, or `skip`.
 
-**Round 3: Development context**
-- Development phase: Prototype / Production / In operation
-- Are there directory conventions or file placement rules AI should follow? (skip if none)
+### Step 3: Run Hearing per Section
 
-### Step 3: Generate and Write
+For each section marked `add` or `update`, run the hearing protocol that `template.md` defines for that section. The catalog specifies the AskUserQuestion text and choices, the inclusion rules, and the per-section output structure.
 
-From collected information, generate project-context SKILL.md following these principles:
+**External Resources section**: follow the routing protocol in `template.md` § External Resources. That section owns the domain multi-select, the domain-to-file slug map, and the per-axis output schema; this command delegates to it.
 
-**Writing principles:**
-1. AI-decidable: Use only measurable and verifiable criteria ("fast" → "within 5 seconds")
-2. Eliminate ambiguity: Include specific numbers, conditions, examples
-3. Positive form: "do this" rather than "don't do that"
-4. Minimal: Only what affects AI execution accuracy
+**Vagueness rejection** (applies to every `add` and `update` section): When a user-provided rule uses subjective phrasing (e.g., "be careful about performance"), follow up with: "How would AI verify this rule passes? Restate it as a measurable check, or reply 'drop' to omit." Keep rules that arrive in measurable form as-is; replace subjective ones with the user's restated version, or omit them when the user replies 'drop'.
 
-**Output targets** (update both):
-1. `.claude/skills/project-context/SKILL.md` (active, read by Claude)
-2. Corresponding `skills-{lang}/project-context/SKILL.md` (check `.claudelang` for current language)
+**Checkpoint**: You hold captured content for every `add` and `update` section, plus the verbatim original content for every `keep` section.
 
-**Structure:**
-```markdown
----
-name: project-context
-description: Provides project-specific prerequisites for AI execution accuracy. Use when checking project structure.
----
+### Step 4: Assemble and Write SKILL.md
+
+Build the rebuilt SKILL.md by concatenating, in this order:
+
+1. Frontmatter — write this canonical block exactly:
+   ```
+   ---
+   name: project-context
+   description: Provides project-specific prerequisites for AI execution accuracy — domain constraints, development phase, directory conventions, external resource access methods. Use when the session starts, when checking project structure, or when a task references domain rules or external resources outside the repository.
+   ---
+   ```
+2. `# Project Context` heading.
+3. Each section in catalog order (Project Overview → Domain Constraints → Development Phase → Directory Conventions → External Resources). The output contains only sections whose disposition is `add`, `keep`, or `update` AND that satisfy their inclusion rule; the body advances directly from one included section to the next.
+
+Write the assembled content to `.claude/skills/project-context/SKILL.md`. This single path is the runtime canonical source read by Claude in every session.
+
+### Step 5: Verify
+
+Apply each check below to the rebuilt `.claude/skills/project-context/SKILL.md`:
+
+- [ ] Frontmatter matches the canonical block in Step 4 verbatim.
+- [ ] Every section heading in the body is followed by captured content from the hearing (concrete values, lists, or sub-blocks).
+- [ ] Every populated section's content matches the output structure that `template.md` defines for it.
+- [ ] Every section in the body has disposition `add`, `keep`, or `update` AND satisfies its inclusion rule.
+- [ ] Domain constraint statements are pass/fail checkable (e.g., "log entries use anonymized IDs" passes; "logs are clean" fails this check).
+- [ ] Project Context content is limited to constraints, phases, conventions, and external resources. Technology stack details belong in the `technical-spec` skill; implementation principles belong in the `coding-standards` skill.
 
-# Project Context
+When any check fails, report the failing check to the user with the specific line and propose either a re-hearing for the affected section or a manual edit. Re-run Step 5 after the fix.
 
-## Project Overview
-- **What this project does**: [concise description]
-- **Domain**: [domain]
+### Step 6: Present Result
 
-## Domain Constraints
-1. [Measurable constraint that affects AI decisions]
-2. [Verifiable requirement]
+Show the rebuilt SKILL.md to the user, list the changes made (added / updated / removed / kept sections), and confirm completion.
 
-## Development Phase
-- **Phase**: [current phase]
+## Output Examples
 
-## Directory Conventions
-[File placement rules, or "No specific conventions" if none]
+**Initial run on an unconfigured skill** (every section freshly captured):
+
+```
+project-context configured:
+- Sections kept: (none — first run)
+- Sections updated: (none — first run)
+- Sections added: Project Overview, Domain Constraints (2 rules captured), Development Phase, Directory Conventions (1 rule), External Resources (Backend domain — Database Schema Source, Secret Store)
+- Sections removed: (none)
+- File written: .claude/skills/project-context/SKILL.md
+```
+
+**Light update on a configured skill** (one section edited, rest preserved):
+
+```
+project-context updated:
+- Sections kept: Project Overview, Development Phase, Directory Conventions
+- Sections updated: Domain Constraints (3 rules captured)
+- Sections added: (none)
+- Sections removed: (none)
+- File written: .claude/skills/project-context/SKILL.md
 ```
 
-### Step 4: Verification
+**Trim run** (an existing section removed, no new ones added):
 
-- [ ] Generated file contains no boilerplate placeholder text ("to be configured", etc.)
-- [ ] All domain constraints are measurable/verifiable (no vague statements)
-- [ ] No technology stack information included (that belongs in technical-spec skill)
-- [ ] No implementation principles included (that belongs in coding-standards skill)
-- [ ] Both output targets updated
-- [ ] Present result to user for confirmation
+```
+project-context updated:
+- Sections kept: Project Overview, Domain Constraints, Development Phase
+- Sections updated: (none)
+- Sections added: (none)
+- Sections removed: Directory Conventions
+- File written: .claude/skills/project-context/SKILL.md
+```