docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

docs/private/roadmap/phases/phase-20-python-integration/planning/python-parser-plan-summary.md

@@ -0,0 +1,148 @@
+# PythonParserBox統合実装計画 - エキスパート評価後の最終版
+作成日: 2025-08-27
+
+## 🎯 革命的な3つの価値
+
+### 1. Pythonエコシステムの即座活用
+- 既存のPythonライブラリをNyashから直接利用可能
+- 段階的な移行パスの提供
+
+### 2. Nyashパーサーのバグ自動検証（Differential Testing）
+- **世界中のPythonコードがNyashのテストケースに！**
+- CPythonをオラクルとして使用、出力・戻り値・例外を自動比較
+- 微妙なセマンティクスバグを大量に発見可能
+
+### 3. 言語成熟度の飛躍的向上
+- 実用的なPythonコードでNyashをストレステスト
+- 発見されたバグ数が成熟度向上の定量的指標
+
+## 🏆 エキスパート評価サマリー
+
+### Gemini先生の評価
+**「非常に野心的で、言語の成熟度を飛躍的に高める可能性を秘めた素晴らしい計画」**
+
+- 技術的に健全なアプローチ
+- pyo3経由のCPythonパーサー利用は最も確実
+- Differential Testingは極めて強力な手法
+
+### Codex先生の評価
+**「Sound approach with strategic strength」**
+
+- 関数単位フォールバックが実用的かつ効果的
+- Python 3.11固定でAST安定性確保
+- テレメトリー重視で継続的改善可能
+
+## 🔑 統合された5つの核心戦略
+
+### 1. 関数単位フォールバック（両エキスパート一致）
+```python
+def supported_function():    # → Nyash MIR/JIT
+    return x + y
+    
+def unsupported_function():  # → CPython exec
+    yield from generator     # Phase 1では未対応
+```
+
+### 2. Python 3.11固定
+- AST安定性確保（3.8 Constant統一、3.10 match/case、3.12位置情報）
+- `py_version`と`ast_format`をJSON IRに埋め込む
+
+### 3. 意味論の正確な実装優先
+Phase 1必須要素（Codex先生強調）：
+- LEGB + locals/freevars（スコーピング）
+- デフォルト引数の評価タイミング（定義時）
+- イテレータベースのfor文
+- for/else + while/else（Python独特）
+- Python真偽値判定（`__bool__` → `__len__`）
+- 短絡評価（and/or）
+
+### 4. GIL管理の最小化
+```rust
+// GILは最小限に！
+let json_ast = Python::with_gil(|py| {
+    py_helper.parse_to_json(py, code)  // Python側でJSON生成
+})?;
+
+// GIL外でRust処理
+let nyash_ast = py.allow_threads(|| {
+    convert_json_to_nyash(json_ast)
+});
+```
+
+### 5. テレメトリー基盤
+```bash
+[PythonParser] Module: example.py (Python 3.11)
+  Functions: 10 total
+  Compiled: 7 (70%)
+  Fallback: 3 (30%)
+    - async_function: unsupported node 'AsyncFunctionDef' at line 23
+```
+
+## 📋 実装フェーズ（詳細版）
+
+### Phase 0: 準備（1週間）
+- [ ] Python 3.11.9環境固定
+- [ ] テレメトリー基盤構築
+- [ ] Differential Testingフレームワーク
+- [ ] JSON IR仕様策定
+
+### Phase 1: Core Subset（2週間）
+- [ ] pyo3統合（prepare_freethreaded_python）
+- [ ] 関数単位コンパイル判定器
+- [ ] 基本構文（def/if/for/while/return）
+- [ ] 意味論必須要素の実装
+- [ ] CPythonとの出力比較テスト
+
+### Phase 2: Data Model（3週間）
+- [ ] 特殊メソッドマッピング
+- [ ] list/dict/tuple実装
+- [ ] 演算子オーバーロード
+
+### Phase 3: Advanced Features（1ヶ月）
+- [ ] 例外処理（try/except）
+- [ ] with文、ジェネレータ
+- [ ] 内包表記、デコレータ
+
+## 📊 成功の測定基準
+
+### 定量的指標
+| 指標 | 目標 | 測定方法 |
+|------|------|----------|
+| カバレッジ率 | 70%以上 | コンパイル済み vs フォールバック関数 |
+| 性能向上 | 2-10倍 | 純Pythonループのベンチマーク |
+| バグ発見数 | 10+件/Phase | Differential Testing |
+| エコシステム | 1以上 | 動作する有名ライブラリ数 |
+
+### マイルストーン
+- Phase 1: "Hello from Python in Nyash"が動作
+- Phase 2: scikit-learnの基本アルゴリズムが動作
+- Phase 3: FlaskのHello Worldが動作
+- Phase 4: PyPIトップ100の30%が基本動作
+
+## 🚨 注意すべき意味論の違い（トップ5）
+
+1. **制御フロー**: for/else, while/else
+2. **スコープ規則**: LEGB、global/nonlocal
+3. **数値演算**: / (true division) vs //
+4. **関数定義**: デフォルト引数は定義時評価
+5. **真偽値判定**: Pythonの__bool__/__len__ルール
+
+## 🎉 期待されるインパクト
+
+### 技術的成果
+- Pythonエコシステムの活用
+- Nyashパーサーの品質向上
+- 性能最適化の実証
+
+### 戦略的価値
+- 言語成熟度の飛躍的向上
+- 開発者コミュニティの拡大
+- 実用アプリケーション開発の加速
+
+## 📝 結論
+
+PythonParserBoxは、単なる機能追加ではなく、**Nyash言語のテスト、デバッグ、エコシステム獲得を同時に加速させる極めて戦略的なプロジェクト**。
+
+両エキスパートの技術的評価と具体的な実装指針により、実現可能性が確認され、明確な実装パスが定まった。
+
+**「Everything is Box」哲学を、言語の壁を超えて実現する革命的な一歩。**