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

docs/private/roadmap/phases/phase-31.3/CHECKLIST.md

@@ -0,0 +1,20 @@
+# CHECKLIST — Phase‑31.3 Selfhost LoopForm
+
+- 形状・支配
+  - [ ] Header/Cond/Body/Latch/Exit の CFG を MIR ダンプで確認
+  - [ ] PHI はブロック先頭のみ（ヘッダ/Exit）
+  - [ ] ret 値は Exit 内定義 or Exit‑PHI（支配OK）
+- 継続/脱出
+  - [ ] continue が Latch へ、break が Exit へジャンプ
+  - [ ] Exit‑PHI へ break/正常脱出の入力が統合
+- Verifier/Fail‑Fast
+  - [ ] 旧命令（BoxCall/ExternCall/NewBox/Print/旧Loop）禁止
+  - [ ] ループ許可エッジ以外のジャンプを拒否
+- テスト
+  - [ ] quick: while/continue/break/if混在 の4本
+  - [ ] quick: MIR スナップ（Exit‑PHI/ret支配）
+  - [ ] integration: VM↔LLVM パリティ（代表2–3本）
+- ロールアウト
+  - [ ] Gate 説明（env）追記、既定ONを明記
+  - [ ] Roadmap 更新（31.2→31.3 の接続）
+

docs/private/roadmap/phases/phase-31.3/INDEX.md

@@ -0,0 +1,21 @@
+# Phase‑31.3 — Gate‑C / Verify 緑化（Selfhost JSON → Mini‑VM）
+
+Status
+- DONE: JsonEmitBox を再帰連結化（blocks/instructions が空になる不具合の根治）
+- DONE: mir_call(Extern) の name 混線（ArrayBox 化）をリテラル保持で回避（Builder に literal パラメータ追加）
+- DONE: スモーク緑化 — `selfhost_mircall_extern_from_builder_vm.sh`
+- TODO: LocalSSA の `.get` 撤退（実行パスを BoxAPI で統一）
+
+What changed
+- Gate‑C JSON 仕様を明文化（docs/reference/mir/json-v0.md）
+- Verify 規則（Phi/Exit/Extern 正規化）を明文化（docs/reference/mir/verify-rules.md）
+- テストガイドに Gate‑C パスを追記（docs/guides/testing.md）
+
+Next
+- 実行パスの `.get` → `call("MapBox.get/2")` / `call("ArrayBox.get/2")` へ統一
+- MirSchema/JsonEmit に dev assert を追加（異常形は早期 Fail‑Fast）
+- Gate‑C 負例スモークの追加（不正 callee/不正 args 形状）
+
+Notes
+- Phi/Exit の Fail‑Fast は Verify に寄せる。Mini‑VM 実装差ではなく形状規約で守る方針。
+- CoreExtern（String/Array/Map）は Extern 統一。strict 検査は `NYASH_VERIFY_CORE_EXTERN=1`。

docs/private/roadmap/phases/phase-31.3/PLAN.md

@@ -0,0 +1,57 @@
+# PLAN — Selfhost LoopForm 実装（Phase‑31.3）
+
+## 0. 背景と狙い
+- 既に Rust 側では LoopFormBox を標準化（ヘッダ/条件/ボディ/ラッチ/出口）。
+- Selfhost 側も同形へ統一し、MIR 形状・Verifier・VM/LLVM パリティを一本化する。
+
+## 1. 要件（技術）
+- 形状: Header → Cond → Branch(Body/Exit), Body → Latch → Header, Exit → ret
+- PHI: ブロック先頭のみ。Exit‑PHI は break/正常脱出の統合。
+- continue: Latch へ。break: Exit へ。いずれも値スナップショットを Exit‑PHI 入力に追加。
+- ret 支配: ret が参照する値は Exit 内定義 or Exit‑PHI（Fail‑Fast）。
+
+## 2. 箱設計（箱言語）
+- LoopFormBox
+  - `new(preheader_bb) -> LoopFormBox`
+  - `build_loop(loop_builder, condition, preheader_vars, body) -> LoopStructure`
+- LoopStructure
+  - `header_bb, condition_bb, body_bb, latch_bb, exit_bb`
+- 依存 / 委譲
+  - LoopCarrierAnalyzerBox: ループキャリア変数（preheader∩body assigns）検出
+  - PhiBuilderBox: Exit‑PHI の一元生成
+  - LoopTraceBox: 最小トレース
+
+## 3. 実装ステップ
+- P1: 構造だけ（Exit‑PHI 生成まで）。continue/break は Latch/Exit へジャンプのみ。
+- P2: continue/break のスナップショット統合。if 内分岐の merge 処理（then/else から merge へ）。
+- P3: Verifier 強化（Exit 支配/PHI先頭限定/許可エッジ）+ MIR スナップショットテスト。
+- P4: Selfhost Compiler（while 糖衣）の降下・接続。Gate 撤退（既定ON）。
+
+## 4. 失敗時方針（Fail‑Fast）
+- 形状破れ（ヘッダ/ラッチ/出口欠落）: 検出時に即エラー。
+- PHI 不正（先頭以外/Incoming 欠落）: Verifier で拒否。
+- continue/break の未設定（latch/exit 無）: 検出時に即エラー。
+
+## 5. ENV/Gate（開発用）
+- `HAKO_USE_LOOPFORM_BOX=1`（既定ON）
+- `HAKO_VERIFY_PHI_STRICT=1`（dev/profile 限定）
+- `HAKO_LOOP_TRACE=1`（最小トレース）
+
+## 6. テスト（最低限）
+- quick
+  - while 最小: 0→5 加算、最終結果
+  - continue: 3 をスキップ
+  - break: 3 で脱出
+  - if 内分岐＋continue/break 混在
+  - MIR スナップショット: Exit‑PHI 形状、ret 値支配
+- integration
+  - VM↔LLVM パリティ: while/continue/break の代表
+
+## 7. ロールアウト
+- dev で Gate ON（既定）。quick/integration 緑維持で既定ON継続。
+- 旧レガシー撤退済（31.2）。影響点は Selfhost 側のみ。
+
+## 8. リスクと対策
+- 例外/throw が導入された後の整合 → 次フェーズで try‑finally ガードを設計。
+- ループ内に複数の return → 現行仕様は Exit 統一。早期 return は禁止または正規化で Exit へ統一。
+

docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt

@@ -0,0 +1,38 @@
+535 pipeline.hako
+249 using_resolver_box.hako
+209 stage1_extract_flow.hako
+187 local_ssa_box.hako
+127 stage1_int_args_extract_box.hako
+118 compare_extract_box.hako
+117 signature_verifier_box.hako
+110 emit_mir_flow.hako
+104 emit_mir_flow_map.hako
+98 stage1_json_scanner_box.hako
+95 regex_flow.hako
+91 mir_call_box.hako
+89 normalizer_box.hako
+69 emit_compare_box.hako
+67 stage1_args_parser_box.hako
+65 pipeline_helpers_box.hako
+62 namespace_box.hako
+60 stage1_name_args_normalizer_box.hako
+49 execution_pipeline_box.hako
+47 map_helpers_box.hako
+38 emit_call_box.hako
+37 json_minify_box.hako
+36 terminator_guard_box.hako
+36 emit_newbox_box.hako
+36 emit_method_box.hako
+34 mir_builder_box.hako
+33 emit_binop_box.hako
+30 readonly_map_view.hako
+29 name_resolve_box.hako
+28 alias_preflight_box.hako
+21 emit_return_box.hako
+20 flow_entry.hako
+16 header_emit_box.hako
+15 pipeline_emit_box.hako
+13 new_extract_box.hako
+13 method_extract_box.hako
+13 call_extract_box.hako
+11 backend_box.hako

docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt

@@ -0,0 +1,44 @@
+315 closure_call_handler.hako
+267 terminator_handler.hako
+235 hakorune_vm_core.hako
+234 phi_handler.hako
+191 boxcall_handler.hako
+157 callee_parser.hako
+152 block_mapper.hako
+130 mircall_handler.hako
+127 args_extractor.hako
+97 instrs_locator.hako
+94 constructor_call_handler.hako
+87 binop_handler.hako
+85 module_function_call_handler.hako
+85 method_call_handler.hako
+79 compare_handler.hako
+71 instruction_dispatcher.hako
+70 json_field_extractor.hako
+66 const_handler.hako
+65 unaryop_handler.hako
+63 typeop_handler.hako
+63 json_scan_guard.hako
+58 newbox_handler.hako
+53 ret_value_loader.hako
+50 global_call_handler.hako
+43 backward_object_scanner.hako
+41 load_handler.hako
+39 store_handler.hako
+38 value_manager.hako
+38 blocks_locator.hako
+38 barrier_handler.hako
+34 json_normalize_box.hako
+34 boxcall_builder.hako
+33 copy_handler.hako
+30 extern_call_handler.hako
+30 block_iterator.hako
+27 instruction_array_locator.hako
+23 receiver_guard.hako
+22 function_locator.hako
+21 map_keys_values_bridge.hako
+21 args_guard.hako
+15 reg_guard.hako
+14 safepoint_handler.hako
+13 nop_handler.hako
+7 error_builder.hako

docs/private/roadmap/phases/phase-31.3/QUICK_START.md

@@ -0,0 +1,366 @@
+# Phase 31.3 Quick Start Guide
+
+**すぐに始められるSelfhost綺麗綺麗計画の最初のステップ**
+
+---
+
+## Week 1 の即座実行タスク（今すぐ開始可能！）
+
+### タスク1: コード品質分析（15分）
+
+```bash
+cd /home/tomoaki/git/hakorune-selfhost
+
+# Compiler分析
+bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
+  lines=$(wc -l < "$file"); \
+  name=$(basename "$file"); \
+  echo "$lines $name"; \
+done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt
+
+# VM分析
+bash -c 'for file in selfhost/hakorune-vm/*.hako; do \
+  lines=$(wc -l < "$file"); \
+  name=$(basename "$file"); \
+  echo "$lines $name"; \
+done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt
+
+# 結果確認
+cat docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt | head -10
+cat docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt | head -10
+```
+
+**期待結果**:
+```
+# Compiler TOP 10
+535 pipeline.hako               ⚠️ 巨大関数（要分割）
+249 using_resolver_box.hako    ⚠️ 要リファクタリング
+209 stage1_extract_flow.hako
+187 local_ssa_box.hako
+...
+
+# VM TOP 10
+315 closure_call_handler.hako  ⚠️ 巨大関数（要分割）
+267 terminator_handler.hako    ⚠️ 要リファクタリング
+235 hakorune_vm_core.hako
+234 phi_handler.hako
+...
+```
+
+---
+
+### タスク2: TraceBox実装（30分）
+
+#### Step 1: ディレクトリ作成
+```bash
+mkdir -p selfhost/shared/trace
+```
+
+#### Step 2: TraceBox実装
+
+**ファイル**: `selfhost/shared/trace/trace_box.hako`
+
+```hakorune
+// TraceBox - 統一トレース出力システム
+// Rust LoopTraceBox の Hakorune版移植
+// Usage: HAKO_TRACE=1 で有効化
+
+static box TraceBox {
+  enabled: IntegerBox
+  prefix: StringBox
+
+  // Constructor
+  birth(enabled, prefix) {
+    me.enabled = enabled
+    me.prefix = prefix
+  }
+
+  // Basic logging
+  log(message) {
+    if me.enabled == 1 {
+      print(me.prefix + message)
+    }
+  }
+
+  // Conditional logging
+  log_if(condition, message) {
+    if me.enabled == 1 && condition == 1 {
+      print(me.prefix + message)
+    }
+  }
+
+  // Formatted logging with value
+  log_value(label, value) {
+    if me.enabled == 1 {
+      print(me.prefix + label + ": " + value)
+    }
+  }
+
+  // Multi-value logging
+  log_values(label, value1, value2) {
+    if me.enabled == 1 {
+      print(me.prefix + label + ": " + value1 + ", " + value2)
+    }
+  }
+
+  // Error logging (always enabled)
+  error(message) {
+    print("[ERROR] " + me.prefix + message)
+  }
+}
+```
+
+**行数**: 約50行 ✅
+
+#### Step 3: hako.toml に追加
+
+**ファイル**: `selfhost/shared/hako.toml`（既存ファイルに追加）
+
+```toml
+[exports]
+# 既存のexports...
+trace = "trace/trace_box.hako"
+```
+
+#### Step 4: 動作確認
+
+**テストファイル**: `apps/examples/trace_test.hako`
+
+```hakorune
+using selfhost.shared.trace as TraceBox
+
+static box Main {
+  main() {
+    // トレース有効（enabled=1）
+    local trace = new TraceBox(1, "[Test] ")
+
+    trace.log("Starting test")
+    trace.log_value("x", 42)
+    trace.log_values("a, b", 10, 20)
+    trace.log_if(1, "Condition is true")
+    trace.log_if(0, "This should NOT appear")
+
+    // トレース無効（enabled=0）
+    local silent = new TraceBox(0, "[Silent] ")
+    silent.log("This should NOT appear")
+
+    // エラーは常に表示
+    trace.error("This is an error")
+
+    return 0
+  }
+}
+```
+
+**実行**:
+```bash
+./target/release/hakorune apps/examples/trace_test.hako
+```
+
+**期待出力**:
+```
+[Test] Starting test
+[Test] x: 42
+[Test] a, b: 10, 20
+[Test] Condition is true
+[ERROR] [Test] This is an error
+```
+
+---
+
+### タスク3: 既存コードへのTraceBox適用（30分）
+
+#### Step 1: pipeline.hakoの冒頭でTraceBox初期化
+
+**ファイル**: `selfhost/compiler/pipeline_v2/pipeline.hako`（既存、編集）
+
+```hakorune
+// 既存のusing文に追加
+using selfhost.shared.trace as TraceBox
+
+flow PipelineV2 {
+  lower_stage1_to_mir_trace(ast_json, prefer_cfg, trace_flag) {
+    // TraceBox初期化
+    local trace = new TraceBox(trace_flag, "[Pipeline] ")
+
+    trace.log("Start: prefer_cfg=" + prefer_cfg)
+
+    // 既存のコード...
+    if ast_json == null {
+      trace.error("ast_json is null")
+      return EmitReturnBox.emit_return_int2(0, 0)
+    }
+
+    // ... 処理 ...
+
+    trace.log("Complete")
+    return mir_json
+  }
+}
+```
+
+#### Step 2: 既存のprint()をtraceに置換（5-10箇所）
+
+**置換パターン**:
+```hakorune
+// Before
+print("[DEBUG] Some message: " + value)
+
+// After
+trace.log_value("Some message", value)
+```
+
+**対象ファイル**（優先順位順）:
+1. `pipeline.hako`（3-5箇所）
+2. `local_ssa_box.hako`（2-3箇所）
+3. `using_resolver_box.hako`（1-2箇所）
+
+#### Step 3: 動作確認
+
+```bash
+# トレース無効（デフォルト）
+./target/release/hakorune apps/selfhost-compiler/main.hako
+
+# トレース有効
+# 注: HAKO_TRACE環境変数の実装は後で（今は trace_flag=1 で直接指定）
+# 暫定的に pipeline.hako 内で trace_flag を 1 にして実行
+```
+
+---
+
+## Week 1 の達成目標
+
+### ✅ 完了チェックリスト
+
+- [ ] **タスク1**: コード品質分析完了（QUALITY_ANALYSIS_*.txt作成）
+- [ ] **タスク2**: TraceBox実装完了（trace_box.hako, 50行）
+- [ ] **タスク3**: 既存コードへのTraceBox適用（5-10箇所）
+- [ ] **テスト**: trace_test.hako実行成功
+- [ ] **ドキュメント**: SELFHOST_QUALITY_REPORT.md作成開始
+
+### 📊 成果物
+
+- `QUALITY_ANALYSIS_COMPILER.txt`: Compiler品質分析
+- `QUALITY_ANALYSIS_VM.txt`: VM品質分析
+- `selfhost/shared/trace/trace_box.hako`: TraceBox実装（50行）
+- `apps/examples/trace_test.hako`: TraceBoxテスト
+- 既存コードのTraceBox適用（5-10箇所）
+
+### 📈 削減/追加行数
+
+- **追加**: +50行（TraceBox）
+- **変更**: 5-10箇所（既存のprint()をtraceに置換）
+
+---
+
+## Week 2 の準備（余裕があれば）
+
+### CompilerConfigBox実装の準備
+
+**ファイル**: `selfhost/compiler/pipeline_v2/compiler_config_box.hako`（新規）
+
+```hakorune
+// CompilerConfigBox - コンパイラ設定の一元管理
+// Rust ConfigBox の Hakorune版
+
+box CompilerConfigBox {
+  prefer_cfg: IntegerBox
+  trace_enabled: IntegerBox
+  trace: TraceBox
+
+  birth(prefer_cfg, trace_enabled) {
+    me.prefer_cfg = prefer_cfg
+    me.trace_enabled = trace_enabled
+    me.trace = new TraceBox(trace_enabled, "[Config] ")
+
+    me.trace.log_value("prefer_cfg", prefer_cfg)
+    me.trace.log_value("trace_enabled", trace_enabled)
+  }
+
+  get_prefer_cfg() {
+    return me.prefer_cfg
+  }
+
+  get_trace() {
+    return me.trace
+  }
+}
+```
+
+**行数**: 約30行
+
+---
+
+## トラブルシューティング
+
+### Q1: TraceBoxのusing文でエラーが出る
+
+**エラー**:
+```
+Unknown module: selfhost.shared.trace
+```
+
+**解決**:
+1. `selfhost/shared/hako.toml` に `trace = "trace/trace_box.hako"` を追加したか確認
+2. ファイルパスが正しいか確認: `selfhost/shared/trace/trace_box.hako`
+3. hako.tomlのsyntaxエラーがないか確認（TOML形式）
+
+---
+
+### Q2: TraceBox.birth()でエラーが出る
+
+**エラー**:
+```
+Constructor birth not found
+```
+
+**解決**:
+TraceBoxは `static box` ではなく `box` として定義する（インスタンス化が必要）
+
+**修正**:
+```hakorune
+// ❌ 誤り
+static box TraceBox { ... }
+
+// ✅ 正しい
+box TraceBox { ... }  // staticなし
+```
+
+---
+
+### Q3: TraceBoxのlog()が何も出力しない
+
+**原因**: `enabled = 0` で初期化されている
+
+**確認**:
+```hakorune
+local trace = new TraceBox(1, "[Test] ")  // enabled=1 にする
+trace.log("Test message")
+```
+
+---
+
+## 次のステップ
+
+Week 1完了後:
+1. **SELFHOST_QUALITY_REPORT.md作成**（分析結果のまとめ）
+2. **Week 2開始**: 箱化パターン確立
+3. **CompilerConfigBox実装**（30行）
+4. **LoopStateBox実装**（80行）
+
+詳細: [SELFHOST_CLEANUP_PLAN.md](./SELFHOST_CLEANUP_PLAN.md)
+
+---
+
+**今すぐ始めましょう！** 🚀
+
+```bash
+# コマンド1つでWeek 1タスク1開始
+cd /home/tomoaki/git/hakorune-selfhost && \
+bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
+  lines=$(wc -l < "$file"); \
+  name=$(basename "$file"); \
+  echo "$lines $name"; \
+done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt && \
+echo "✅ QUALITY_ANALYSIS_COMPILER.txt created!"
+```

docs/private/roadmap/phases/phase-31.3/README.md

@@ -0,0 +1,66 @@
+# Phase‑31.3 — Selfhost LoopForm 実装計画（Hakorne Script）
+
+目的
+- Rust 側で安定化した LoopFormBox（ヘッダ/条件/ボディ/ラッチ/出口の正規形）を、Selfhost（Hakorne Script）にも導入し、IR/MIR/VM の“ループの顔”を一本化する。
+- PHI の生成位置・支配関係・continue/break の意味論をドキュメント＋スモークで固定し、Fail‑Fast を徹底する。
+
+範囲
+- Selfhost VM/Builder/Emitter の最小セット（while/continue/break/if 内分岐）。
+- 依存箱（LoopCarrierAnalyzerBox, PhiBuilderBox, LoopTraceBox）の薄実装または委譲。
+- LLVM ハーネスはパリティ確認のみ（機能追加なし）。
+
+非対象（本フェーズ外）
+- for/foreach 糖衣の拡張（次期）
+- 例外伝播/try‑finally のループ内整合（次期）
+
+受け入れ基準（Definition of Done）
+- MIR 形状
+  - Loop は Header/Cond/Body/Latch/Exit を持つ単純 CFG に正規化。
+  - PHI はブロック先頭のみ。Exit の ret 値は Exit 内定義または Exit‑PHI を必須。
+- 継続/脱出
+  - continue は Latch に、break は Exit にジャンプ。PHI 入力は continue/break を統合。
+- Fail‑Fast
+  - 未定義のレガシー命令（BoxCall/ExternCall/NewBox/Print/旧Loop 等）は Verifier が拒否。
+- パリティ
+  - VM↔LLVM で代表ループ（while/continue/break/分岐）出力が一致（数本）。
+- スモーク
+  - quick/integration で緑（Loop 関連）。MIR スナップショットで PHI 形状を固定。
+
+参考（最小 MIR 形状スナップショット）
+```
+{
+  "functions": [
+    { "name": "main",
+      "blocks": [
+        {"id": 0, "instructions": [
+          {"op":"jump", "target": 1}
+        ]},
+        {"id": 1, "instructions": [
+          {"op":"phi", "dst": 10, "values": [{"block":0,"value":1},{"block":2,"value":11}]},
+          {"op":"branch", "cond": 3, "then": 2, "else": 3}
+        ]},
+        {"id": 2, "instructions": [
+          {"op":"jump", "target": 1}
+        ]},
+        {"id": 3, "instructions": [
+          {"op":"phi", "dst": 20, "values": [{"block":1,"value":10},{"block":2,"value":12}]},
+          {"op":"ret", "value": 20}
+        ]}
+      ]
+    }
+  ]
+}
+```
+要点
+- ヘッダ/Exit の先頭にのみ `op:"phi"` が現れる。
+- `ret.value` は Exit 内で定義された `dst`（例では `20`）を参照する。
+
+進め方（小さく段階導入）
+- P1: LoopFormBox の最小実装（構造生成＋Exit‑PHI 生成）
+- P2: continue/break の値スナップショット統合＋if 内分岐の merge 処理
+- P3: Verifier 強化（Exit 支配／PHI 先頭限定／Latch→Header のみ許可）
+- P4: Selfhost Compiler への接続（while 糖衣→LoopForm 降下）＋ Env Gate 撤退（既定ON）
+
+関連ドキュメント
+- call 統一: `docs/reference/mir/call-unified.md`
+- 旧ループ撤退: `docs/private/roadmap/phases/phase-31.2/`

docs/private/roadmap/phases/phase-31.3/SUMMARY.md

@@ -0,0 +1,325 @@
+# Phase 31.3 Summary - エグゼクティブサマリー
+
+**Selfhost 綺麗綺麗計画: 10週間でHakorune本流化を達成**
+
+作成日: 2025-10-19
+対象読者: プロジェクトオーナー、PM、アーキテクト
+
+---
+
+## 🎯 核心目標（30秒で理解）
+
+**Phase 31（Rustリファクタリング）で得た5つの知見をSelfhost（Hakoruneスクリプト版）に適用し、Hakorune本流化を完成させる**
+
+1. ✅ **loopform完全実装**（VM + Compiler + Golden Test）
+2. ✅ **Rust MIR vs Hakorune MIR 完全パリティ**（95%以上）
+3. ✅ **コード品質向上**（最大関数150行以下、状態箱化、トレース統一化）
+4. ✅ **ドキュメント整備**（実装ガイド、対応表、レポート）
+
+**期間**: 10週間（Phase 1-4）
+**削減/追加**: +4,440-6,290行（コード +1,940-2,490行、ドキュメント +2,500-3,800行）
+
+---
+
+## 📊 現状（Phase 31.3開始前）
+
+### Selfhost Compiler（selfhost/compiler/pipeline_v2/）
+- **総行数**: 3,007行（38ファイル）
+- **最大ファイル**: pipeline.hako（535行）⚠️ 巨大関数
+- **実装済み**: 基本MIR生成、制御フロー（if/match）、SSA、Using/名前空間
+- **未実装**: **loopform命令生成**、ループ専用PHI、トレース統一化
+
+### Selfhost VM（selfhost/hakorune-vm/）
+- **総行数**: 3,455行（67ファイル）
+- **実装済み命令**: 22種類（16 MIR + 6 advanced = **138%カバレッジ**！）
+- **最大ファイル**: closure_call_handler.hako（315行）
+- **未実装**: **loopform命令ハンドラ**
+
+### 評価
+- ✅ **基盤は完成**（22命令ハンドラ、@match-based dispatch、Result-based error handling）
+- ❌ **loopform未実装**（Compiler + VM）
+- ❌ **Rust MIR パリティ未達成**（loop構文が動作しない）
+- ⚠️ **巨大関数あり**（pipeline.hako 535行、closure_call_handler.hako 315行）
+
+---
+
+## 🚀 Phase 31.3 の構成（10週間）
+
+### Phase 1: 基盤整備（Week 1-2）
+**目標**: トレース統一化、箱化パターン確立
+
+**主要成果物**:
+- TraceBox実装（50行）⭐Rust LoopTraceBox移植
+- CompilerConfigBox実装（30行）
+- LoopStateBox実装（80行）
+- コード品質レポート
+
+**削減/追加**: +160行
+
+---
+
+### Phase 2: loopform実装（Week 3-5）⭐最重要
+**目標**: loop構文をloopform命令に変換、VM実行可能に
+
+**主要成果物**:
+- **VM**: loopform_handler.hako（150-200行）
+- **Compiler**: loop_emit_box.hako（200-250行）+ phi_emit_box.hako（150-200行）
+- **Golden Test基礎**: Golden Testフレームワーク（100-150行）
+- **テスト**: 10-15ケース
+
+**削減/追加**: +800-1,100行
+
+**実装詳細**:
+1. Week 3: VM loopform実装（Rust `handlers/flow.rs` 参考）
+2. Week 4: Compiler loop/phi実装（Rust `loop_builder/build.rs` 参考）
+3. Week 5: Golden Test（Rust MIR vs Hakorune MIR 一致確認）
+
+---
+
+### Phase 3: リファクタリング（Week 6-8）
+**目標**: コード品質向上、保守性向上
+
+**主要成果物**:
+- 巨大関数分割:
+  - pipeline.hako（535行 → 150行以下）
+  - closure_call_handler.hako（315行 → 200行以下）
+- 状態管理箱化:
+  - CompilerStateBox実装（100行）
+  - VMStateBox実装（80行）
+- Legacy削除（-100〜-200行）
+
+**削減/追加**: +580行、-100〜-200行
+
+---
+
+### Phase 4: Golden Testing + ドキュメント（Week 9-10）
+**目標**: Rust vs Hakorune 完全パリティ、ドキュメント整備
+
+**主要成果物**:
+- **Golden Test**: 50-100ケース全PASS（パリティ95%以上）
+- **IMPLEMENTATION_GUIDE.md**（1,000-1,500行）
+- **RUST_HAKORUNE_MAPPING.md**（500-800行）
+- **CLEANUP_REPORT.md**（800-1,200行）
+
+**削減/追加**: +3,300-4,800行（ドキュメント主体）
+
+---
+
+## 📈 Rust知見の適用（5つのパターン）
+
+### 1. LoopTraceBox → TraceBox
+**適用可能性**: ⭐⭐⭐⭐⭐ 高（P0）
+- トレース出力の統一化（Compiler + VM）
+- 環境変数制御（HAKO_TRACE=1）
+- デバッグ効率化
+
+### 2. PhiBuilderBox → PhiEmitBox ⭐最重要
+**適用可能性**: ⭐⭐⭐⭐⭐ 高（P0）
+- 3層PHI生成（Header/Latch/Exit）
+- break/continue完全サポート
+- Rust実装の直接移植
+
+### 3. LoopContextBox → LoopStateBox
+**適用可能性**: ⭐⭐⭐⭐ 高（P1）
+- ループ状態管理の一元化
+- break/continueスタックの明示化
+
+### 4. 巨大関数分割 → オーケストレーション層
+**適用可能性**: ⭐⭐⭐⭐⭐ 高（P1）
+- pipeline.hako（535行 → 150行以下）
+- 単一責務の原則徹底
+- テスト容易性向上
+
+### 5. Legacy削除 → 単一経路化
+**適用可能性**: ⭐⭐⭐ 中（P2）
+- loopform経路のみ（legacy経路なし）
+- 未使用コード削除（-100〜-200行）
+
+---
+
+## 💰 ROI（投資対効果）
+
+### 投資
+- **時間**: 10週間（約2.5ヶ月）
+- **工数**: 1人月 × 2.5ヶ月 = 2.5人月
+- **リスク**: loopform実装の複雑性（中）、Hakorune構文の制約（中）
+
+### リターン
+1. **機能面**:
+   - ✅ Selfhost単体でloop実行可能
+   - ✅ Rust MIR vs Hakorune MIR 完全パリティ（95%以上）
+2. **品質面**:
+   - ✅ 最大関数サイズ: 150行以下
+   - ✅ 保守性・可読性の大幅向上
+3. **戦略面**:
+   - ✅ Hakorune本流化（Phase 15.76/15.77への準備完了）
+   - ✅ Rust層最小化の準備（99.8%削減へ）
+
+### ROI評価: ⭐⭐⭐⭐⭐ 極めて高い
+- Selfhost本流化の必須ステップ
+- Phase 15.76/15.77への橋渡し
+- 世界レベルの保守性・可読性達成
+
+---
+
+## 🎯 マイルストーン（4つの検問）
+
+| Week | マイルストーン | 成功基準 | リスク |
+|------|---------------|---------|-------|
+| **2** | 基盤整備完了 | TraceBox実装、箱化パターン確立 | 低 |
+| **5** | loopform実装完了 | VM実行可能、Golden Test基礎 | **高**⚠️ |
+| **8** | リファクタリング完了 | 最大関数150行以下、状態箱化 | 低 |
+| **10** | Selfhost本流化完成 | Golden Test全PASS、ドキュメント完備 | 中 |
+
+**Critical Path**: Week 3-5（loopform実装）⚠️ 最重要区間
+
+---
+
+## 🔥 リスク管理
+
+### リスク1: loopform実装の複雑性（Week 3-5）
+**確率**: ⭐⭐⭐ 中 | **影響**: ⭐⭐⭐⭐⭐ 高
+
+**軽減策**:
+- ✅ Rust実装（build.rs, 128行）を参考
+- ✅ 段階的実装（VM → Compiler → Golden Test）
+- ✅ 週次レビュー（早期問題発見）
+
+### リスク2: Hakorune構文の制約
+**確率**: ⭐⭐⭐ 中 | **影響**: ⭐⭐⭐ 中
+
+**軽減策**:
+- ✅ 簡略化設計（Rust実装の複雑なパターンを避ける）
+- ✅ 箱化パターン確立（Week 2）
+- ✅ ドキュメント化（制約事項を明記）
+
+### リスク3: パリティ未達成（Week 5, 9）
+**確率**: ⭐⭐ 低 | **影響**: ⭐⭐⭐⭐⭐ 高
+
+**軽減策**:
+- ✅ Golden Testフレームワーク早期構築（Week 5）
+- ✅ 継続的なパリティ確認
+- ✅ 正規化・ソートによる差分吸収
+
+### リスク4: スコープクリープ（全期間）
+**確率**: ⭐⭐⭐⭐ 高 | **影響**: ⭐⭐⭐ 中
+
+**軽減策**:
+- ✅ 80/20ルール徹底（完璧より進捗）
+- ✅ 追加機能は `docs/development/proposals/ideas/` に記録
+- ✅ 週次レビューで進捗確認
+
+---
+
+## 🔗 長期ビジョン（Phase 15.76/15.77連携）
+
+### Phase 31.3完了後の展開
+
+**Phase 15.76: extern_c戦略**（+4週間）
+- C ABI経由でLLVMバックエンド連携
+- extern_c構文実装
+- AOT導線確立
+
+**Phase 15.77: 凍結EXE確定**（+6週間）
+- hako-frozen-v1.exe作成・配布
+- Rust層最小化（99.8%削減: 99,406行 → 100-200行）
+- Selfhost = 主要開発
+
+**合計タイムライン**: 20週間（約5ヶ月）
+- Phase 31.3: 10週間（本計画）
+- Phase 15.76: 4週間
+- Phase 15.77: 6週間
+
+---
+
+## 📋 即座に開始可能なアクション
+
+### Action 1: コード品質分析（15分）
+```bash
+cd /home/tomoaki/git/hakorune-selfhost
+bash docs/private/roadmap/phases/phase-31.3/quick_quality_check.sh
+```
+
+### Action 2: TraceBox実装（30分）
+```bash
+mkdir -p selfhost/shared/trace
+# → trace_box.hako実装（QUICK_START.md参照）
+```
+
+### Action 3: Week 1計画レビュー（10分）
+```bash
+cat docs/private/roadmap/phases/phase-31.3/QUICK_START.md
+```
+
+---
+
+## 📚 ドキュメント構成（2,068行）
+
+| ドキュメント | 行数 | サイズ | 対象読者 |
+|------------|-----|-------|---------|
+| **SELFHOST_CLEANUP_PLAN.md** | 1,250 | 39KB | PM/実装者 ⭐完全計画 |
+| **QUICK_START.md** | 366 | 8.3KB | 実装者 ⭐即座実行 |
+| **README.md** | 234 | 6.6KB | すべて ⭐概要 |
+| **INDEX.md** | 218 | 7.9KB | すべて ⭐索引 |
+| **合計** | **2,068** | **62KB** | - |
+
+---
+
+## 🎯 決定が必要な事項
+
+### 即座の決定（Week 1開始前）
+1. ✅ **Phase 31.3の承認**（10週間計画）
+2. ✅ **Week 1開始のGO判断**（TraceBox実装 + 品質分析）
+3. ✅ **リソース確保**（実装者1名 × 10週間）
+
+### 計画中の決定（Week 3開始前）
+4. ⏳ **loopform設計レビュー**（Rust実装との差分確認）
+5. ⏳ **Golden Test基準策定**（パリティ95%は適切か？）
+
+### 後回し可能（Week 6以降）
+6. 🔄 **リファクタリングのスコープ調整**（P1/P2の優先順位）
+7. 🔄 **ドキュメントの詳細度調整**（実装ガイドの粒度）
+
+---
+
+## 🚀 推奨アクション
+
+### Phase 31.3を**承認して即座に開始**すべき理由:
+
+1. ✅ **Phase 31完了の直後**が最適（知見が新鮮、Rust実装が参照可能）
+2. ✅ **Selfhost本流化の必須ステップ**（Phase 15.76/15.77への橋渡し）
+3. ✅ **投資対効果が極めて高い**（2.5人月で世界レベルの保守性達成）
+4. ✅ **リスクは管理可能**（段階的実装、週次レビュー、80/20ルール）
+5. ✅ **基盤は完成済み**（Hakorune VM 138%カバレッジ、@match-based dispatch完備）
+
+### 次のステップ（今日中に実施可能）:
+
+```bash
+# 1. ドキュメント確認（15分）
+cd /home/tomoaki/git/hakorune-selfhost
+cat docs/private/roadmap/phases/phase-31.3/README.md
+cat docs/private/roadmap/phases/phase-31.3/QUICK_START.md
+
+# 2. コード品質分析（15分）
+bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
+  lines=$(wc -l < "$file"); name=$(basename "$file"); echo "$lines $name"; \
+done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt
+
+# 3. Week 1開始（TraceBox実装、30分）
+mkdir -p selfhost/shared/trace
+# → trace_box.hako実装
+```
+
+---
+
+## 📞 問い合わせ
+
+- **計画詳細**: [SELFHOST_CLEANUP_PLAN.md](./SELFHOST_CLEANUP_PLAN.md)
+- **即座実行**: [QUICK_START.md](./QUICK_START.md)
+- **索引**: [INDEX.md](./INDEX.md)
+
+---
+
+**Phase 31.3: Selfhost 綺麗綺麗計画 - 今すぐ始めましょう！** 🚀
+
+**Hakoruneが世界に誇るセルフホストシステムになる第一歩です。**

docs/private/roadmap/phases/phase-31.3/quick_quality_check.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Quick Quality Check Script for Phase 31.3
+# Usage: bash docs/private/roadmap/phases/phase-31.3/quick_quality_check.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../../.." && pwd)"
+
+echo "🔍 Phase 31.3 Quick Quality Check"
+echo "=================================="
+echo ""
+
+cd "$PROJECT_ROOT"
+
+# Compiler analysis
+echo "📊 Compiler Analysis (selfhost/compiler/pipeline_v2/)"
+echo "-----------------------------------------------------"
+bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do
+  if [ -f "$file" ]; then
+    lines=$(wc -l < "$file")
+    name=$(basename "$file")
+    echo "$lines $name"
+  fi
+done | sort -rn' > "$SCRIPT_DIR/QUALITY_ANALYSIS_COMPILER.txt"
+
+echo "Total files: $(ls -1 selfhost/compiler/pipeline_v2/*.hako 2>/dev/null | wc -l)"
+echo "Total lines: $(cat selfhost/compiler/pipeline_v2/*.hako 2>/dev/null | wc -l)"
+echo ""
+echo "Top 10 largest files:"
+head -10 "$SCRIPT_DIR/QUALITY_ANALYSIS_COMPILER.txt"
+echo ""
+
+# VM analysis
+echo "📊 VM Analysis (selfhost/hakorune-vm/)"
+echo "---------------------------------------"
+bash -c 'for file in selfhost/hakorune-vm/*.hako; do
+  if [ -f "$file" ]; then
+    lines=$(wc -l < "$file")
+    name=$(basename "$file")
+    echo "$lines $name"
+  fi
+done | sort -rn' > "$SCRIPT_DIR/QUALITY_ANALYSIS_VM.txt"
+
+echo "Total files: $(ls -1 selfhost/hakorune-vm/*.hako 2>/dev/null | wc -l)"
+echo "Total lines: $(cat selfhost/hakorune-vm/*.hako 2>/dev/null | wc -l)"
+echo ""
+echo "Top 10 largest files:"
+head -10 "$SCRIPT_DIR/QUALITY_ANALYSIS_VM.txt"
+echo ""
+
+# Instruction handlers
+echo "📦 VM Instruction Handlers"
+echo "--------------------------"
+echo "Total handlers: $(ls -1 selfhost/hakorune-vm/*_handler.hako 2>/dev/null | wc -l)"
+echo ""
+ls -1 selfhost/hakorune-vm/*_handler.hako 2>/dev/null | while read file; do
+  name=$(basename "$file" .hako)
+  lines=$(wc -l < "$file")
+  printf "  %-30s %4d lines\n" "$name" "$lines"
+done | sort -k2 -rn | head -10
+echo ""
+
+# Summary
+echo "📝 Summary"
+echo "----------"
+echo "✅ QUALITY_ANALYSIS_COMPILER.txt created"
+echo "✅ QUALITY_ANALYSIS_VM.txt created"
+echo ""
+echo "📋 Next Steps:"
+echo "  1. Review QUALITY_ANALYSIS_*.txt files"
+echo "  2. Read docs/private/roadmap/phases/phase-31.3/QUICK_START.md"
+echo "  3. Start Week 1: TraceBox implementation"
+echo ""
+echo "🚀 Phase 31.3 ready to start!"