# Phase 20.23-20.26 Complete Planning Index

**作成日**: 2025-10-30
**ステータス**: ✅ 完全版計画策定完了

---

## 📚 Document Structure

このディレクトリには Phase 20.23-20.26 の完全計画が含まれています。

### 🎯 Start Here（はじめに）

1. **[EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)** ⭐ **最優先**
   - 3分で全体像を把握
   - User の critical insight
   - Before/After 比較
   - 主要成果まとめ

2. **[TIMELINE_COMPARISON.md](TIMELINE_COMPARISON.md)** ⭐ **視覚的比較**
   - Before/After タイムライン可視化
   - リスク推移グラフ
   - Cost-Benefit 分析
   - Gantt チャート

3. **[PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)** ⭐ **詳細分析**
   - Option A vs B vs C 比較
   - Why Option A is best
   - リスクマトリックス
   - 推奨実装順序

---

## 📖 Phase-by-Phase Plans

### Phase 20.23: Arc/RefCell in Hakorune（2-3週間）

**文書**: [README.md](README.md)

**概要**:
- Hakorune 実装（C ではない！）
- Policy-Data plane separation
- GcBox pattern 踏襲

**削減**: -0 lines（foundation phase）
**追加**: +100 lines C, +200 lines Hakorune
**リスク**: LOW ✅
**期間**: 2-3 weeks

**Key Sections**:
- Executive Summary: Why Hakorune, not C
- Architecture Design: ArcBox/RefCellBox API
- Week-by-Week Plan: 実装詳細
- C Side Minimal API: 100行のみ追加

---

### Phase 20.24: Parser削除（1-2ヶ月）

**文書**: [../phase-20.24/README.md](../phase-20.24/README.md)

**概要**:
- Rust Parser/AST 完全削除
- Hakorune Parser に完全移行
- Instant value delivery

**削減**: **-10,500 lines** ⚡（-9.0%）
**リスク**: LOW ✅
**期間**: 1-2 months

**Key Sections**:
- Deletion Targets: src/parser/, src/ast/
- Month 1: Gate & Validation
- Month 2: Deletion & Cleanup
- Acceptance Criteria: 296/296 tests PASS

---

### Phase 20.25: Box System + MIR Builder削除（2-3ヶ月）

**文書**: [../phase-20.25/README.md](../phase-20.25/README.md)

**概要**:
- MIR Builder/Optimizer/VM/Box System 削除
- 50% Rust 削減（最大マイルストーン）
- P0 Blockers 解決必須

**削減**: **-22,193 lines** ⚡（-19.0%）
**累計**: **-32,693 lines**（-28.0%）
**リスク**: MEDIUM ⚠️（P0 blocker 依存）
**期間**: 2-3 months

**Key Sections**:
- Month 1: MIR Builder/Optimizer deletion（P0 fixes）
- Month 2: Rust VM deletion（Bridge-B optimization）
- Month 3: Box System deletion（Arc/RefCell integration）
- P0 Blockers: Bridge-B timeout, map_len bug

---

### Phase 20.26: Final Rust Consolidation（2-3ヶ月）

**文書**: [../phase-20.26/README.md](../phase-20.26/README.md)

**概要**:
- Rust 層最終整理
- hakmem アロケータ統合
- True Self-Hosting 達成

**削減**: **-61,713 lines** ⚡（-52.8%）
**累計**: **-94,406 lines**（-80.8%）🔥
**最終状態**: Rust ~5,000 lines（8.3%）
**リスク**: MEDIUM ⚠️（hakmem integration）
**期間**: 2-3 months

**Key Sections**:
- Month 1: Audit & Wave 1 deletion（LLVM/WASM）
- Month 2: Plugin System & Kernel migration
- Month 3: hakmem integration & Final cleanup
- Final State: Rust = Floor, Hakorune = House ✅

---

## 🎯 Critical Documents

### For Decision Makers

1. **[EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)**
   - High-level overview
   - Key decisions
   - ROI analysis
   - Approval checklist

2. **[TIMELINE_COMPARISON.md](TIMELINE_COMPARISON.md)**
   - Visual comparison
   - Cost-benefit analysis
   - Risk progression charts

### For Implementers

1. **[README.md](README.md)** (Phase 20.23)
   - Week-by-week implementation plan
   - Technical specifications
   - Testing strategy

2. **[PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)**
   - Why this order works
   - Alternative options rejected
   - Risk mitigation strategies

### For Reviewers

1. All Phase READMEs
   - Detailed acceptance criteria
   - Risk analysis
   - Rollback plans

---

## 📊 Key Metrics Summary

### Duration

| Phase | Duration | Cumulative |
|-------|----------|------------|
| 20.23 | 2-3 weeks | 2-3 weeks |
| 20.24 | 1-2 months | 3-4 months |
| 20.25 | 2-3 months | 5-7 months |
| 20.26 | 2-3 months | **6-9 months** ✅ |

### Lines Deleted

| Phase | Lines Deleted | Cumulative | % Reduction |
|-------|---------------|------------|-------------|
| 20.23 | -0 | -0 | 0% |
| 20.24 | -10,500 | -10,500 | -9.0% |
| 20.25 | -22,193 | -32,693 | -28.0% |
| 20.26 | -61,713 | **-94,406** | **-80.8%** 🔥 |

### Risk Level

| Phase | Risk Level | Rationale |
|-------|-----------|-----------|
| 20.23 | LOW ✅ | Hakorune implementation, GcBox pattern |
| 20.24 | LOW ✅ | Complete duplication, well-tested |
| 20.25 | MEDIUM ⚠️ | P0 blockers, Bridge-B optimization |
| 20.26 | MEDIUM ⚠️ | hakmem integration, large-scale cleanup |

---

## 🔥 Critical Insight Impact

**User の発見**:
> "Arc/RefCell はHakoruneスクリプトで実装するやつじゃない？"

**Before**: C implementation（2-3 months, HIGH risk）
**After**: Hakorune implementation（2-3 weeks, LOW risk）

**Impact**:
- ✅ **Time savings**: ~2.5 months（10-11 weeks）⚡
- ✅ **Risk reduction**: HIGH → LOW
- ✅ **Complexity reduction**: C low-level → Hakorune script
- ✅ **Maintainability**: C code → Hakorune code
- ✅ **Total reduction**: -32,693 → -94,406 lines（**2.9x improvement**）🔥

**Pattern**: **Policy（Hakorune）vs Data（C）plane separation**

**Precedent**: `lang/src/runtime/gc/gc_box.hako`（既に検証済み）

---

## 🎯 Recommended Phase Order

### **Option A: Arc/RefCell First, Parser Second** ✅ Chosen

**Rationale**: Foundation → Value → Major Work → Cleanup

**Timeline**:
```
Phase 20.23: Arc/RefCell (2-3 weeks)   ← Foundation ✅
Phase 20.24: Parser削除 (1-2 months)   ← Value ✅
Phase 20.25: Box System削除 (2-3 mon)  ← Major Work ⚠️
Phase 20.26: Final Rust削除 (2-3 mon)  ← Cleanup ⚠️
```

**Why This Order**:
1. ✅ Natural dependency flow（Arc/RefCell → Box System）
2. ✅ Low risk start（2-3週間で基盤確立）
3. ✅ Consistent momentum（Small → Big → Huge wins）
4. ✅ Early testing（Box System 時に Arc/RefCell 運用実績あり）
5. ✅ Simple rollback（各 Phase ごとに checkpoint）

**Risk Progression**: **LOW → LOW → MEDIUM → MEDIUM** ✅

**Alternative Options**:
- Option B（Parser First）: ⚠️ Momentum gap（2-3週間停滞）
- Option C（Parallel Tracks）: ❌ High coordination overhead

**Details**: [PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)

---

## ✅ Success Criteria

### Quantitative Goals

- [ ] **Duration**: 6-9 months total
- [ ] **Lines Deleted**: -94,406 lines（-80.8%）
- [ ] **Rust Layer**: ≤5,000 lines（8.3%）
- [ ] **Hakorune Layer**: ~55,000 lines（91.7%）
- [ ] **Test Coverage**: 296/296 smoke tests PASS
- [ ] **Performance**: ±10-20% vs original Rust

### Qualitative Goals

- [ ] **True Self-Hosting**: Rust = Floor, Hakorune = House ✅
- [ ] **Clean Architecture**: Policy-Data plane separation
- [ ] **Memory Safety**: hakmem + Arc/RefCell 完全自律
- [ ] **Maintainability**: Hakorune code > C/Rust code
- [ ] **Documentation**: Each phase fully documented
- [ ] **CI Green**: Daily regression tests passing

---

## 🚨 Critical Risks & Mitigation

### Phase-Level Risks

| Phase | Critical Risk | Mitigation |
|-------|--------------|------------|
| 20.23 | Atomic ops bug | C11 standard, existing patterns |
| 20.24 | Import cleanup miss | Cargo check + CI |
| 20.25 | **P0 Blockers** 🔥 | Week 1-2 専任対応 |
| 20.26 | hakmem stability | Extensive testing, fallback |

### P0 Blockers（Most Critical）

**Phase 20.25 Week 1-2 Must-Fix**:

1. **Bridge-B Timeout** 🔥
   - Current: 60s timeout → no result
   - Target: 300s timeout + heartbeat
   - Priority: **P0 - Blocks everything**

2. **map_len Returns 0** 🔥
   - Current: `MapBox.len()` returns 0（expected: 2）
   - Target: Correct value returned
   - Priority: **P0 - Collection tests fail**

**Mitigation**:
- [ ] Dedicated 1-2 week focus（Week 1-2 of Phase 20.25）
- [ ] No other work until P0 resolved
- [ ] Escalate if not resolved in 2 weeks

---

## 📁 File Structure

```
phase-20.23/
├── INDEX.md                      ← This file（全体ナビゲーション）
├── EXECUTIVE_SUMMARY.md          ← 3分概要（最優先）
├── TIMELINE_COMPARISON.md        ← 視覚的比較（Gantt, charts）
├── PHASE_ORDER_ANALYSIS.md       ← 詳細分析（Option A vs B vs C）
└── README.md                     ← Phase 20.23 実装計画

phase-20.24/
└── README.md                     ← Phase 20.24 実装計画（Parser削除）

phase-20.25/
└── README.md                     ← Phase 20.25 実装計画（Box System削除）

phase-20.26/
└── README.md                     ← Phase 20.26 実装計画（Final Rust削除）
```

---

## 🔗 Related Documents

### Prerequisites（前提フェーズ）

- **Phase 20.20**: [C ABI Export via LLVM](../phase-20.20/README.md)
- **Phase 20.21**: [Manual Memory Management](../phase-20.21/README.md)
- **Phase 20.22**: [String/Array C-ABI](../phase-20.22/README.md)

### Reference Materials

- **Rust Removal Roadmap**: [rust-removal-comprehensive-roadmap.md](../../../development/analysis/rust-removal-comprehensive-roadmap.md)
- **GcBox Pattern**: `lang/src/runtime/gc/gc_box.hako`
- **hakmem PoC**: `apps/experiments/hakmem-poc/`
- **Bridge-B Implementation**: `src/backend/mir_interpreter/exec.rs:297-338`
- **Hakorune VM**: `lang/src/runtime/vm/`

---

## 🎉 Expected Final State

### Before Phase 20.23

```
┌────────────────────────────────────────────────┐
│ Rust Layer: 99,406 lines (85.1%)               │
│ ├── Parser/AST (10,500)                        │
│ ├── MIR Builder/Optimizer (3,800)              │
│ ├── Rust VM (2,393)                            │
│ ├── Box System (16,000)                        │
│ ├── LLVM/WASM backends (6,751)                 │
│ ├── Plugin System (10,000)                     │
│ ├── Kernel (8,000)                             │
│ └── Other (41,962)                             │
└────────────────────────────────────────────────┘

Hakorune Layer: 17,435 lines (14.9%)

Ratio: 85% Rust : 15% Hakorune
```

### After Phase 20.26

```
┌────────────────────────────────────────────────┐
│ Rust Layer: ~5,000 lines (8.3%) ✅             │
│ ├── HostBridge API (~500)                      │
│ ├── CLI Minimal (~1,000)                       │
│ ├── hakmem Binding (~500)                      │
│ └── Essential MIR Types (~3,000)               │
└────────────────────────────────────────────────┘

┌────────────────────────────────────────────────┐
│ Hakorune Layer: ~55,000 lines (91.7%) ✅       │
│ ├── Compiler (12,000)                          │
│ ├── VM (5,000)                                 │
│ ├── Box System (15,000)                        │
│ ├── Plugin System (5,000)                      │
│ ├── Kernel (5,000)                             │
│ ├── Standard Library (10,000)                  │
│ └── Other (3,000)                              │
└────────────────────────────────────────────────┘

hakmem (C): ~6,500 lines

Ratio: 8% Rust : 92% Hakorune : Minimal C ✅
```

**Achievement**: ✅ **True Self-Hosting** - Rust = Floor, Hakorune = House

---

## 🚀 Next Steps

### Immediate（Week 1）

1. [ ] **Review all documents** with stakeholders
2. [ ] **Approve Phase 20.23** commencement
3. [ ] **Set up tracking** (GitHub milestones, issues)
4. [ ] **Kickoff meeting** with team

### Phase 20.23 Start（Week 1-3）

1. [ ] Week 1: C data plane implementation
2. [ ] Week 2: Hakorune policy plane implementation
3. [ ] Week 3: Integration & testing
4. [ ] Checkpoint: Arc/RefCell complete ✅

### Beyond（Month 2+）

- [ ] Phase 20.24: Parser削除
- [ ] Phase 20.25: Box System削除
- [ ] Phase 20.26: Final Rust削除
- [ ] **Completion**: True Self-Hosting ✅

---

## 📞 Questions & Clarifications

**Have questions?** Check these resources:

1. **High-level overview**: [EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)
2. **Visual timeline**: [TIMELINE_COMPARISON.md](TIMELINE_COMPARISON.md)
3. **Detailed analysis**: [PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)
4. **Implementation details**: Each Phase's README.md

**Still unclear?** Contact plan author for clarification.

---

## ✅ Approval Status

- [ ] **Documents reviewed**: Executive Summary + Timeline + Phase Order Analysis
- [ ] **Phase READMEs reviewed**: 20.23, 20.24, 20.25, 20.26
- [ ] **Risks understood**: P0 blockers, hakmem integration
- [ ] **Resources confirmed**: 1 team, 6-9 months
- [ ] **Rollback plan accepted**: Git tags, backup branches
- [ ] **Go/No-Go decision**: [ ] GO [ ] NO-GO

---

**Created**: 2025-10-30
**Status**: ✅ Complete plan ready for approval
**Recommendation**: **Approve and commence Phase 20.23** ✅
**Expected Completion**: May-Aug 2026（6-9 months from start）