refine(design-doc): evidence-backed behavioral claim verification

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

@@ -100,6 +100,7 @@ For WorkPlan, additionally verify:
 - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
 - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`)
+- **Behavioral claim evidence check**: Scan the Design Doc for behavioral or factual claims it relies on but does not itself define, whose falsity would invalidate the design approach — framework/library default behavior, a capability assumed already provided, or a feature assumed already implemented; declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely scan starting points (a hint set, not exhaustive). Treat a claim already recorded in the Fact Disposition Table (Codebase Analysis-surfaced facts) or Cross-Layer Assumptions (prior-layer claims) as correctly routed, and exclude it from this check. For each remaining claim, the Agreement Checklist "Assumed Behaviors" slot must record it with either attached evidence (codebase file:line, command result, or an authoritative doc paired with the resolved package version) and Confirmed: Yes, or Confirmed: No plus a matching Risks and Mitigation row (matched by the restated claim) naming how it will be verified or guarded. Flag as an `important` issue (category: `feasibility`) any remaining claim that is: absent from the slot; Confirmed: Yes without attached evidence; a framework/library default marked Confirmed: Yes whose evidence lacks a resolved package version; Confirmed: No without a matching Risks and Mitigation row; or Confirmed: No whose matching Risks and Mitigation row lacks a downstream `verify at [step or artifact]` propagation (a concrete reference to a Verification Strategy or WorkPlan step)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
 - **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword
 - **Code verification integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code verification with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check

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

@@ -14,11 +14,10 @@ You are a frontend technical design specialist AI assistant for creating Archite
 **Current Date Confirmation**: Before starting work, check the current date with the `date` command to use as a reference for determining the latest information.
 
 ### Applying to Implementation
-- Apply documentation-criteria skill for documentation creation criteria
+- Apply in their stated domains: documentation-criteria, project-context.
 - Apply frontend-technical-spec skill for frontend technical specifications (React, build tool, environment variables)
 - Apply frontend-typescript-rules skill for frontend TypeScript development rules (function components, Props-driven design)
 - Apply coding-standards skill for universal coding standards and pre-implementation existing code investigation process
-- Apply project-context skill for project context
 - Apply implementation-approach skill for metacognitive strategy selection process (used for implementation approach decisions)
 - Apply typescript-testing skill for test design standards (testable AC format, coverage requirements)
 - Apply llm-friendly-context skill for clarity of generated artifacts and handoffs (explicit inputs, decisions, output shape, and success criteria)
@@ -93,7 +92,14 @@ The subsections below are not parallel mandates; they form four serial gates: **
    - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
    - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies
 
-5. **Include in Design Doc**
+5. **Behavioral Claim Verification**
+   - For each behavioral or factual claim the design relies on but does not itself define, and whose falsity would invalidate the design approach — framework/library default behavior ("the router preserves scroll by default", "the form library resets on unmount"), a capability assumed already provided ("the hook already debounces", "the context already exposes Z"), or a feature assumed already implemented ("already handled by the parent") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL. For a framework/library default, pair the official doc with the resolved package version (from the lockfile or config), since default behavior can differ across versions. Declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely starting points (a hint set, not exhaustive).
+   - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes.
+   - Claim without locatable evidence → record it in the same slot with Confirmed: No and Evidence: Not located, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. Propagate that resolution downstream as `verify at [step or artifact]` so it becomes a Verification Strategy or WorkPlan task rather than ending as a record.
+   - Scope and routing: record here only the behavioral assumptions the designer introduces that are not already recorded elsewhere. When a claim also qualifies for another destination, route it there first — a structural existing-behavior fact surfaced by Codebase Analysis goes to the Fact Disposition Table; a claim inherited from a prior-layer Design Doc goes to Cross-Layer Assumptions.
+   - Gate timing: the "Assumed Behaviors" slot sits under the Gate 0 Agreement Checklist but is completed here in Gate 1, since evidence collection depends on the code investigation above. Leaving it empty or provisional when the rest of the Agreement Checklist is first filled is expected; this deferred write does not violate Gate Ordering.
+
+6. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
    - Clearly document similar component search results (found components or "none")
    - Include dependency existence verification results (verified existing / requires new creation)
@@ -215,19 +221,7 @@ For each integration boundary, define the contract:
 Confirm and document conflicts with existing components (naming conventions, prop patterns) at each integration point.
 
 ### Change Impact Map [Gate 3 — Required]
-Must be included when creating Design Doc:
-
-```yaml
-Change Target: UserProfileCard component
-Direct Impact:
-  - src/components/UserProfileCard/UserProfileCard.tsx (Props change)
-  - src/pages/ProfilePage.tsx (usage site)
-Indirect Impact:
-  - User context (data format change)
-  - Theme settings (style prop additions)
-No Ripple Effect:
-  - Other components, API endpoints
-```
+Required when creating a Design Doc. Record three tiers (see design-template.md for the YAML skeleton): **Direct Impact** (components/files changed and their usage sites), **Indirect Impact** (downstream effects — data format, context/state, style props), **No Ripple Effect** (areas explicitly unaffected).
 
 ### Interface Change Impact Analysis [Gate 3 — Required]
 

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

@@ -14,11 +14,8 @@ You are a technical design specialist AI assistant for creating Architecture Dec
 **Current Date Confirmation**: Before starting work, check the current date with the `date` command to use as a reference for determining the latest information.
 
 ### Applying to Implementation
-- Apply documentation-criteria skill for documentation creation criteria
-- Apply technical-spec skill for project technical specifications
-- Apply typescript-rules skill for TypeScript development rules
+- Apply in their stated domains: documentation-criteria, technical-spec, typescript-rules, project-context.
 - Apply coding-standards skill for universal coding standards and pre-implementation existing code investigation process
-- Apply project-context skill for project context
 - Apply implementation-approach skill for metacognitive strategy selection process (used for implementation approach decisions)
 - Apply llm-friendly-context skill for clarity of generated artifacts and handoffs (explicit inputs, decisions, output shape, and success criteria)
 
@@ -93,7 +90,14 @@ The subsections below are not parallel mandates; they form four serial gates: **
    - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
    - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies
 
-5. **Record findings in Design Doc**
+5. **Behavioral Claim Verification**
+   - For each behavioral or factual claim the design relies on but does not itself define, and whose falsity would invalidate the design approach — framework/library default behavior ("X defaults to Y"), a capability assumed already provided ("the service already returns Z", "the endpoint already validates W"), or a feature assumed already implemented ("already handled upstream") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL. For a framework/library default, pair the official doc with the resolved package version (from the lockfile or config), since default behavior can differ across versions. Declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely starting points (a hint set, not exhaustive).
+   - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes.
+   - Claim without locatable evidence → record it in the same slot with Confirmed: No and Evidence: Not located, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. Propagate that resolution downstream as `verify at [step or artifact]` so it becomes a Verification Strategy or WorkPlan task rather than ending as a record.
+   - Scope and routing: record here only the behavioral assumptions the designer introduces that are not already recorded elsewhere. When a claim also qualifies for another destination, route it there first — a structural existing-behavior fact surfaced by Codebase Analysis goes to the Fact Disposition Table; a claim inherited from a prior-layer Design Doc goes to Cross-Layer Assumptions.
+   - Gate timing: the "Assumed Behaviors" slot sits under the Gate 0 Agreement Checklist but is completed here in Gate 1, since evidence collection depends on the code investigation above. Leaving it empty or provisional when the rest of the Agreement Checklist is first filled is expected; this deferred write does not violate Gate Ordering.
+
+6. **Record findings in Design Doc**
    - "## Existing Codebase Analysis": investigation results, similar-functionality search results (matches or "none"), dependency existence (verified / external / requires new creation), adopted decision (use existing / improvement proposal / new implementation) with rationale.
    - "## Code Inspection Evidence": all inspected files and key functions, each tagged with relevance (similar functionality / integration point / pattern reference).
 
@@ -224,19 +228,7 @@ For each integration boundary, define the contract:
 Confirm and document conflicts with existing systems (priority, naming conventions) at each integration point.
 
 ### Change Impact Map [Gate 3 — Required]
-Must be included when creating Design Doc:
-
-```yaml
-Change Target: UserService.authenticate()
-Direct Impact:
-  - src/services/UserService.ts (method change)
-  - src/api/auth.ts (call site)
-Indirect Impact:
-  - Session management (token format change)
-  - Log output (new fields added)
-No Ripple Effect:
-  - Other services, DB structure
-```
+Required when creating a Design Doc. Record three tiers (see design-template.md for the YAML skeleton): **Direct Impact** (files/methods changed and their call sites), **Indirect Impact** (downstream effects — data format, timing, log output), **No Ripple Effect** (areas explicitly unaffected).
 
 ### Field Propagation Map [Gate 3 — Required when fields cross component boundaries]
 When new or changed fields cross component boundaries:

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

@@ -100,6 +100,7 @@ WorkPlanの場合、追加で以下を確認:
 - 失敗シナリオ検証：正常系・高負荷・外部障害の失敗シナリオを特定し、どの設計要素がボトルネックになるか指摘
 - コード調査エビデンス検証：調査ファイルが設計スコープに関連するか確認、主要な関連ファイルの漏れを指摘
 - 依存先の実在性検証：Design Docの「既存コードベース分析」セクションが「既存」と記述する依存先について、Grep/Globでコードベース内の定義を確認。コードベースに見つからず公式の外部出典の記載もない → `critical`（カテゴリ: `feasibility`）。存在するが定義のシグネチャ（メソッド名、パラメータ型、戻り値型）がDesign Docの記述と乖離 → `important`（カテゴリ: `consistency`）
+- **振る舞いに関する主張のエビデンスチェック**: Design Doc が依存するが自身では定義しておらず、誤っていれば設計方針が破綻する振る舞い・事実の主張をスキャンする — フレームワーク/ライブラリのデフォルト挙動、既に提供されていると想定する能力、既に実装済みと想定する機能。「already」「by default」「defaults to」「handled by」「既に」「デフォルトで」「デフォルトは」「処理済み」「〜で処理する」「自動的に」といった断定的な言い回しがスキャンの起点になりやすい（網羅ではない）。Fact Disposition Table（Codebase Analysis が明らかにした事実）や Cross-Layer Assumptions（前レイヤーの主張）に既に記録されている主張は正しく振り分けられているものとして扱い、本チェックの対象から除外する。残りの各主張について、「合意事項チェックリスト」の Assumed Behaviors スロットが、根拠（コードベースの file:line、コマンド結果、または解決したパッケージバージョンとセットの公式ドキュメント）付きで 確認: 済 として記録しているか、または 確認: 未 として対応する「リスクと対策」の行（再掲した主張で対応付け）を持ち、どう検証/ガードするかを記していることを確認する。残りの主張のうち次に該当するものを `important`（カテゴリ: `feasibility`）として指摘する: スロットに存在しない; 確認: 済 だが根拠が添付されていない; 確認: 済 だがフレームワーク/ライブラリのデフォルトで根拠に解決したパッケージバージョンがない; 確認: 未 だが対応する「リスクと対策」の行がない; または 確認: 未 だが対応する「リスクと対策」の行に下流の `検証先: [ステップまたは成果物]` 伝播（検証戦略または作業計画書のステップへの具体的参照）がない
 - **既存実装ドキュメント検証**: コード検証結果が提供され、ドキュメントが既存実装を記述している場合（将来の要件ではなく）、コードから観察可能な振る舞いが事実として記述されていることを検証する。確定的な振る舞いに対する推測的な表現 → `important`
 - **データ設計完全性チェック**: ドキュメントにデータ格納キーワード（database, persistence, storage, migration）またはデータアクセスキーワード（repository, query, ORM, SQL）またはデータスキーマキーワード（table, schema, column）が含まれるにもかかわらず、データ設計コンテンツが不足している場合（スキーマ参照なし、データ層戦略を含む「テスト境界」セクションなし、データモデル文書なし） → `important`（カテゴリ: `completeness`）。注: 「model」「field」「record」「entity」等の汎用語のみでは本チェックを発火しない — データ格納またはデータアクセスキーワードとの共起が必要
 - **コード検証連携**: `code_verification`入力が提供された場合、`undocumentedDataOperations`の各項目がドキュメントに不在 → `important`（カテゴリ: `completeness`）。コード検証のseverityが`critical`または`major`の不整合 → 対応するレビューチェックの事前検証エビデンスとして組み込む