refactor: Config層独立化 + コード品質改善 + テスト拡充

## Config層の独立化 (Clean Architecture)
- config/types.py: Config専用TypedDict定義
- config/exceptions.py: ConfigError例外クラス
- config/constants.py: LEVEL_CONFIG定数（SSoT）
- config/error_messages.py: シンプルなエラーメッセージ関数
- config/validation.py: collect_type_error関数
- 8つの既存configファイルからdomain importを削除

## コード品質改善
- domain/validators/type_validators.py: 型検証のSingle Source of Truth
- infrastructure/error_handling.py: 統一エラー処理ユーティリティ
- application/validators.py: 新type_validatorsに委譲
- mypy型エラー修正 (domain/exceptions.py, config/threshold_provider.py)

## テスト拡充 (+85テスト)
- test_cli.py: Config CLI テスト (10)
- test_protocols.py: Protocol テスト (12)
- test_version.py: バージョン テスト (10)
- test_type_validators.py: 型検証 テスト (35)
- test_error_handling.py: エラー処理 テスト (17)
- test_threshold_equals_one修正: 閾値=1環境を作成するように変更

## 結果
- pytest: 1460 passed, 3 skipped (Windowsでの権限テストのみ)
- mypy: エラーなし
- ruff: 修正済み

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: web-flow

EpisodicRAG/CONTRIBUTING.md

@@ -428,6 +428,47 @@ python -c "from domain import __version__; print(__version__)"
 
 ---
 
+## Documentation Sync Process
+
+### Bilingual Documentation Policy
+
+EpisodicRAGプラグインは日本語を主言語とし、主要ドキュメントの英語版を提供しています。
+
+1. **Primary Language**: Japanese (日本語)
+2. **Secondary Language**: English
+
+> **翻訳方針**: 主要ドキュメント（README, QUICKSTART, CHEATSHEET）のみ英語版を維持します。その他のドキュメントは日本語のみとし、翻訳の維持コストを抑えます。
+
+### Currently Synced Files
+
+| Japanese | English | Status |
+|----------|---------|--------|
+| `README.md` | `README.en.md` | ✅ Synced |
+| `docs/user/QUICKSTART.md` | `docs/user/QUICKSTART.en.md` | ✅ Synced |
+| `docs/user/CHEATSHEET.md` | `docs/user/CHEATSHEET.en.md` | ✅ Synced |
+
+### Sync Workflow
+
+日本語ドキュメントを更新した場合、対応する英語ドキュメントも同期してください。
+
+1. **Edit Japanese version first** - 日本語版を先に編集
+2. **Update English version** - 同じPR内で英語版を更新
+3. **Add sync header** - 英語ファイルの先頭にヘッダーを追加:
+   ```markdown
+   <!-- Last synced: YYYY-MM-DD -->
+   ```
+
+### Adding New Translations
+
+新しい英語翻訳を追加する場合:
+
+1. Copy structure from Japanese version（日本語版の構造をコピー）
+2. Translate content maintaining formatting（フォーマットを維持して翻訳）
+3. Add sync header with date（同期ヘッダーを追加）
+4. Update this table（上のテーブルを更新）
+
+---
+
 ## サポート
 
 質問や問題がある場合は、GitHub Issuesで報告してください。

EpisodicRAG/README.md

@@ -227,22 +227,32 @@ L00001追加 → `/digest`せず → L00002追加
 
 ### 記憶定着サイクル
 
-```text
-Loop追加 → `/digest` → Loop追加 → `/digest` → ...
-         ↑ 記憶定着  ↑         ↑ 記憶定着
+EpisodicRAGの最も重要な原則は、**Loopを追加したら都度 `/digest` を実行する**ことです。
+
+```mermaid
+flowchart LR
+    A[Loop追加] --> B["/digest"]
+    B --> C[記憶定着]
+    C --> A
+
+    style B fill:#90EE90,stroke:#228B22
+    style C fill:#87CEEB,stroke:#4169E1
 ```
 
-この原則を守ることで、AIは全てのLoopを記憶できます。
+**やるべきこと:**
+```text
+L00001追加 → /digest → L00002追加 → /digest → ...
+```
 
 **やってはいけないこと:**
-
 ```text
-L00001追加 → `/digest`せず → L00002追加
-                              ↑
-                    この時点でAIはL00001の内容を覚えていない
-                    （記憶がまだら＝虫食い状態）
+L00001追加 → L00002追加 → /digest
+                 ↑
+       この時点でL00001の内容をAIは覚えていない（まだらボケ）
 ```
 
+この原則を守ることで、AIは全てのLoopを記憶できます。
+
 ### Threshold（閾値）
 **定義**: 各階層のDigest生成に必要な最小ファイル数
 

EpisodicRAG/docs/dev/API_REFERENCE.md

@@ -4,6 +4,8 @@
 
 EpisodicRAGプラグインの**Python API仕様書**です。
 
+> **設計方針**: このドキュメントはSSoT原則に従い、リンク集として機能します。詳細な定義は各 `api/*.md` を参照してください。
+
 > **対応バージョン**: EpisodicRAG Plugin（[version.py](../../scripts/domain/version.py) 参照）/ ファイルフォーマット 1.0
 
 > 📖 用語・共通概念: [用語集](../../README.md)
@@ -48,45 +50,11 @@ Clean Architecture（4層構造）に基づいて、APIドキュメントを層
 
 ### 推奨インポートパス
 
-```python
-# Domain層（定数・型・例外）
-from domain import LEVEL_CONFIG, __version__, ValidationError
-from domain.file_naming import extract_file_number, format_digest_number
-from domain.level_registry import get_level_registry
-
-# Infrastructure層（外部I/O）
-from infrastructure import load_json, save_json, log_info, log_error
-from infrastructure.file_scanner import scan_files
-from infrastructure.user_interaction import get_default_confirm_callback
-
-# Application層（ビジネスロジック）
-from application.shadow import ShadowTemplate, ShadowUpdater, CascadeProcessor
-from application.grand import GrandDigestManager, ShadowGrandDigestManager
-from application.finalize import RegularDigestBuilder, DigestPersistence
-from application.validators import validate_dict, is_valid_list
-
-# Interfaces層（エントリーポイント）
-from interfaces import DigestFinalizerFromShadow, ProvisionalDigestSaver
-from interfaces.interface_helpers import sanitize_filename, get_next_digest_number
-from interfaces.provisional import InputLoader, DigestMerger
-
-# 設定（configパッケージ）
-from config import DigestConfig
-```
+> 📖 完全なインポートパスは [ARCHITECTURE.md#推奨インポートパス](ARCHITECTURE.md#推奨インポートパス) を参照
 
 ### 依存関係ルール
 
-```text
-domain/           ← 何にも依存しない（純粋なビジネスロジック）
-    ↑
-infrastructure/   ← domain/ のみ
-    ↑
-application/      ← domain/ + infrastructure/
-    ↑
-interfaces/       ← application/
-```
-
-> 📖 **アーキテクチャ詳細**: [ARCHITECTURE.md](ARCHITECTURE.md#clean-architecture)
+> 📖 詳細は [ARCHITECTURE.md#依存関係ルール](ARCHITECTURE.md#依存関係ルール) を参照
 
 ---
 

EpisodicRAG/docs/user/FAQ.md

@@ -20,6 +20,10 @@ EpisodicRAGプラグインに関するよくある質問と回答集です。
 - [一般的な質問](#一般的な質問)
 - [導入・セットアップ](#導入セットアップ)
 - [日常的な使い方](#日常的な使い方)
+- [パフォーマンスと最適化](#パフォーマンスと最適化)
+- [バックアップと復旧](#バックアップと復旧)
+- [マルチユーザー・同時アクセス](#マルチユーザー同時アクセス)
+- [他ツールとの連携](#他ツールとの連携)
 - [トラブルシューティング](#トラブルシューティング)
 - [開発者向け](#開発者向け)
 - [関連ドキュメント](#関連ドキュメント)
@@ -114,6 +118,105 @@ flowchart TB
 
 ---
 
+## パフォーマンスと最適化
+
+### Q: 100件以上のLoopファイルがある場合、パフォーマンスに影響はありますか？
+
+**A**: EpisodicRAGは大量のファイルを効率的に処理するよう設計されています。
+
+- ファイルスキャンは増分検出（`last_digest_times.json`）で最適化
+- 1000ファイルでも5秒以内で検出完了
+- メモリ使用量は500ダイジェストで1MB未満
+
+### Q: ストレージ要件はどのくらいですか？
+
+**A**: 目安として：
+
+| ファイル種類 | サイズ目安 |
+|------------|----------|
+| Loopファイル | 1-10KB/件 |
+| Weeklyダイジェスト | 5-20KB/件 |
+| ShadowGrandDigest | 50-200KB |
+| GrandDigest | 100-500KB |
+
+**例**: 100 Loops + 20 Weeklies ≈ 2-3MB
+
+---
+
+## バックアップと復旧
+
+### Q: バックアップはどのように取るべきですか？
+
+**A**: 以下のディレクトリをバックアップしてください（優先順）：
+
+1. `Loops/` - 元データ（**最重要**）
+2. `Essences/` - GrandDigest, ShadowGrandDigest
+3. `.claude-plugin/config.json` - 設定
+4. `.claude-plugin/last_digest_times.json` - 状態追跡
+
+> 💡 Loops/さえあれば他は再構築可能です。
+
+### Q: ShadowGrandDigestが破損した場合の復旧方法は？
+
+**A**:
+1. `ShadowGrandDigest.txt`を削除
+2. `/digest` を実行して再構築
+
+> 📖 詳細: [TROUBLESHOOTING.md](TROUBLESHOOTING.md#shadowgranddigest更新されない)
+
+### Q: 誤ってファイルを削除してしまいました
+
+**A**: 復旧手順は削除したファイルによって異なります：
+
+| 削除ファイル | 復旧方法 |
+|------------|---------|
+| Loopファイル | Gitバックアップから復元、または手動で再作成 |
+| ShadowGrandDigest | `/digest`を実行して再生成 |
+| GrandDigest | `/digest weekly`を実行して再生成 |
+| config.json | `@digest-setup`を実行して再作成 |
+
+---
+
+## マルチユーザー・同時アクセス
+
+### Q: 複数人で同じリポジトリを使えますか？
+
+**A**: 現在の設計は**単一ユーザー**を想定しています。
+
+- **読み取り**: 問題なし（複数人で同時閲覧可能）
+- **書き込み**: 競合の可能性あり（同時に`/digest`を実行すると不整合が発生する可能性）
+
+> 💡 チーム利用の場合は、各メンバーが独自のプラグインインスタンスを持つことを推奨します。
+
+### Q: 同時に複数のターミナルから操作できますか？
+
+**A**: 推奨しません。
+
+- `/digest`実行中に別ターミナルで`/digest`を実行するとファイル競合が発生する可能性があります
+- 1つのターミナルで操作を完了してから次の操作を開始してください
+
+---
+
+## 他ツールとの連携
+
+### Q: 他のClaude Codeプラグインと併用できますか？
+
+**A**: はい。EpisodicRAGは独立して動作します。
+
+- 設定ディレクトリは`.claude-plugin/`で分離
+- 他プラグインとの干渉なし
+- コマンド名が重複しない限り問題なく併用可能
+
+### Q: GitHubとの連携は可能ですか？
+
+**A**: はい。[ADVANCED.md](ADVANCED.md)でGitHub連携の設定方法を説明しています。
+
+- Loops/Essencesディレクトリをリポジトリに含める
+- `.gitignore`でキャッシュファイルを除外
+- 複数デバイス間での記憶共有が可能
+
+---
+
 ## トラブルシューティング
 
 問題が発生した場合は [TROUBLESHOOTING.md](TROUBLESHOOTING.md) を参照してください。

EpisodicRAG/docs/user/GUIDE.md

@@ -18,31 +18,7 @@
 
 ### 記憶定着サイクル
 
-EpisodicRAGの最も重要な原則は、**Loopを追加したら都度 `/digest` を実行する**ことです。
-
-```mermaid
-flowchart LR
-    A[Loop追加] --> B["/digest"]
-    B --> C[記憶定着]
-    C --> A
-
-    style B fill:#90EE90,stroke:#228B22
-    style C fill:#87CEEB,stroke:#4169E1
-```
-
-**やるべきこと:**
-```text
-L00001追加 → /digest → L00002追加 → /digest → ...
-```
-
-**やってはいけないこと:**
-```text
-L00001追加 → L00002追加 → /digest
-                 ↑
-       この時点でL00001の内容をAIは覚えていない（まだらボケ）
-```
-
-> 📖 まだらボケの詳細は [用語集](../../README.md#まだらボケ) を参照
+> 📖 記憶定着サイクルの詳細は [用語集](../../README.md#記憶定着サイクル) を参照
 
 ---
 

EpisodicRAG/scripts/application/validators.py

@@ -13,50 +13,15 @@
     files = validate_list(source_files, "source_files")
 """
 
-from typing import Any, Callable, Dict, List, Optional, Type, TypeVar
+from typing import Any, Dict, List, Optional
 
 from domain.error_formatter import get_error_formatter
 from domain.exceptions import ValidationError
 from domain.validation import validate_type as _validate_type
-
-# =============================================================================
-# 汎用ヘルパー関数（内部使用）
-# =============================================================================
-
-T = TypeVar('T')
-
-# _validate_type は domain.validation から再エクスポート（後方互換性維持）
-
-
-def _is_valid_type(data: Any, expected_type: Type[T]) -> bool:
-    """
-    汎用型チェックヘルパー（例外を投げない）
-
-    Args:
-        data: 検証対象のデータ
-        expected_type: 期待する型
-
-    Returns:
-        dataが期待する型ならTrue
-    """
-    return isinstance(data, expected_type)
-
-
-def _get_or_default(data: Any, expected_type: Type[T], default_factory: Callable[[], T]) -> T:
-    """
-    汎用デフォルト取得ヘルパー
-
-    Args:
-        data: 検証対象のデータ
-        expected_type: 期待する型
-        default_factory: デフォルト値を生成する関数
-
-    Returns:
-        dataが期待する型ならdata、そうでなければdefault_factory()の結果
-    """
-    if isinstance(data, expected_type):
-        return data
-    return default_factory()
+from domain.validators import (
+    get_or_default as _get_or_default,
+    is_valid_type as _is_valid_type,
+)
 
 
 # =============================================================================

EpisodicRAG/scripts/config/__init__.py

@@ -37,10 +37,10 @@
 from pathlib import Path
 from typing import List, Literal, Optional
 
-# Domain層からインポート
-from domain.error_formatter import get_error_formatter
-from domain.exceptions import ConfigError
-from domain.types import ConfigData
+# Config層専用の型・例外・エラーメッセージ
+from .exceptions import ConfigError
+from .types import ConfigData
+from .error_messages import initialization_failed_message
 
 # 内部コンポーネント
 from .config_loader import ConfigLoader
@@ -124,8 +124,7 @@ def __init__(self, plugin_root: Optional[Path] = None):
             self._directory_validator = self._config_validator
 
         except (PermissionError, OSError) as e:
-            formatter = get_error_formatter()
-            raise ConfigError(formatter.config.initialization_failed("configuration", e)) from e
+            raise ConfigError(initialization_failed_message("configuration", e)) from e
 
     # =========================================================================
     # Context Manager Support

EpisodicRAG/scripts/config/cli.py

@@ -45,9 +45,13 @@ def main(plugin_root: Optional[Path] = None) -> None:
             # デフォルト: JSON出力
             print(json.dumps(config.config, indent=2, ensure_ascii=False))
 
-    except FileNotFoundError as e:
-        sys.stderr.write(f"[ERROR] {e}\n")
-        sys.exit(1)
+    except (FileNotFoundError, Exception) as e:
+        # ConfigError やその他のエラーをキャッチ
+        from .exceptions import ConfigError
+        if isinstance(e, (FileNotFoundError, ConfigError)):
+            sys.stderr.write(f"[ERROR] {e}\n")
+            sys.exit(1)
+        raise
 
 
 if __name__ == "__main__":