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

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

@@ -0,0 +1,7 @@
+- [x] ny-llvmc harness: JSON→IR→obj/exe path wired for AOT canaries（正例3本 PASS）
+- [x] libhakorune_runtime.a minimal（console/time/mem/string/array）配置検出（target/release）
+- [x] link: AOT build script produces EXE（tools/hakorune/aot_build.sh）
+- [x] canaries: return/binop/if build+run（rc/出力整合）
+- [x] negative: extern-missing（PASS）/ div0（ハーネス仕様によりビルド失敗許容へ）
+- [x] docs: AOT pipeline（guides/aot-build.md）、runtime spec（specs/runtime-min-api.md）
+- [ ] CLI thin delegator（任意; dev only; Rust凍結を維持）

docs/private/roadmap/phases/phase-20.30/CLAUDE_SPEC.md

@@ -0,0 +1,28 @@
+# Phase‑20.30 — Claude Handoff Spec (AOT Bring‑Up)
+
+Scope
+- Implement a dev AOT pipeline: MIR(JSON v0) → LLVM IR → object → EXE using ny‑llvmc harness.
+- Ship a minimal static runtime lib and a small build script; keep Rust frozen (no new semantics).
+
+Tasks
+- Harness
+  - Add a thin driver to call ny‑llvmc with JSON input and produce IR/object.
+  - Numeric returns map to rc; print last numeric line.
+- Runtime
+  - Provide/point to `libhakorune_runtime.a` with console/time/mem/string/array minimal.
+  - Ensure symbol names are documented and stable.
+- Build script
+  - `tools/hakorune/aot_build.sh`: emit JSON via lang, compile with ny‑llvmc, link runtime → EXE.
+  - Env: `HAKO_AOT_RUNTIME_PATH`, `HAKO_AOT_LD_FLAGS` (dev only).
+- Canaries
+  - Build and run `return 7`, `1+2*3`, and simple `if`.
+  - Negative: div0; missing extern → stable tag.
+- Docs
+  - Usage and constraints; no changes to default behavior.
+
+Non‑goals
+- Dynamic plugin matrix; performance work; new VM semantics in Rust.
+
+Acceptance
+- AOT canaries pass locally via script; PR includes docs and minimal scaffolding only.
+

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

@@ -0,0 +1,57 @@
+# Phase‑20.30 — Execution Plan (AOT Bring‑Up)
+
+Milestones
+
+1) AOT toolchain path (harness‑first)
+- Choose ny‑llvmc harness for IR/object emission (no new Rust semantics).
+- Contract: JSON v0 in, single main function out; numeric return maps to rc.
+
+2) Runtime static lib (minimal)
+- Provide `libhakorune_runtime.a` (C) with: console.{log|warn|error}, time.now_ms, mem.{alloc|free|name}, String helpers, Array minimal (size/get/set/pop), Map stub or plugin‑only guard.
+- Document headers and ABI entrypoints; keep symbols stable.
+
+3) Link step + wrapper
+- Script `tools/hakorune/aot_build.sh` (dev) to: emit JSON → ny‑llvmc → link runtime → produce EXE.
+- Env toggles: HAKO_AOT_RUNTIME_PATH, HAKO_AOT_LD_FLAGS (dev only).
+
+4) Canaries
+- AOT return/binop/if build+run; rc parity（return/binop=7, if=1）
+- Negative: extern-missing（ビルド失敗 or 実行非0 を PASS とする）, div by zero（ビルド失敗 or 実行非0 を PASS とする）
+
+5) Docs + CLI glue (optional)
+- Document AOT workflow and constraints; add `--aot` thin CLI delegator that shells out to script (dev only) without adding Rust semantics.
+
+Success criteria
+- End‑to‑end: hakorune‑frozen builds hakorune‑new (hello AOT) and tiny programs run.
+- Rust freeze honored (no new runtime semantics implemented in Rust).
+
+---
+
+# Rust‑Freeze + Hako Engine Bring‑Up (P0/P1)
+
+Objective
+- 減速無しで「脱Rust」を段階導入。既存のRust実行層は凍結し、Hakorune側エンジン（Core/VM）を優先経路として増強する。
+
+Scope（今回）
+- P0（2週間）: エンジン選択トグルと Gate‑C の既定化（ドキュメント）
+  - Runner に `--engine {rust|hakorune}` / `HAKO_VM_ENGINE=hakorune` を追加（既定OFF）。
+  - quick/integration-core の opt‑in カナリアで Hako エンジンを観測（Fail‑Fast 厳守）。
+  - Gate‑C(JSON→Core) を quick で第一候補として“明文化”。README/Smokes に記載。
+
+- P1（3〜4週間）: JSON 処理の Hako 側への薄移管
+  - 既存の `lang/src/vm/core/json_v0_reader.hako` を Gate‑B/C 境界で共通 reader として再利用。
+  - 最小 emitter（const/ret/binop）を Hako 側に追加し、Rust emit と opt‑in で並行運用。
+  - SSOT生成は現行 `tools/hakorune/gen_ssot.sh` を継続（失敗時は現行fallback）。
+
+- P1'（並行 1週間）: I/O Bridge の最小C‑ABI
+  - print/read_all など最小APIのみ（console/time/fsはゲートで制御）。
+  - Gate: `HAKO_KNI_{TIME|FS}=1` が無い場合は Fail‑Fast。
+
+Acceptance
+- quick/integration-core が両エンジン（rust/hakorune）で opt‑in 緑。
+- Gate‑C 直行の file/pipe × plugins ON/OFF が対称（既存カナリアで担保）。
+- AOT 代表（return/binop/if）を自走で生成・実行可能（既存 canary で担保）。
+
+Notes
+- plugin 依存ケースは preflight＋トグル（SMOKES_ENABLE_PLUGINS_CANARY=1）で厳密にゲートする。
+- 実行意味論の追加は Hako 側のみ。Rust は「橋・ローダ・Fail‑Fast」以外は凍結し、差分最小を維持する。

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

@@ -0,0 +1,24 @@
+# Phase‑20.30 — Self‑Contained AOT Build (Go‑style bootstrap)
+
+Purpose
+- Produce a self‑contained Hakorune binary via LLVM AOT so “Hakorune builds Hakorune” becomes practical (Go‑style).
+
+In‑scope
+- MIR(JSON v0) → LLVM IR → object → EXE (AOT path, harness first).
+- Minimal runtime static lib packaging for AOT (string/array/map day‑1, console, time, mem).
+- Dev wrapper/script to drive end‑to‑end: lang emit → AOT → run.
+
+Out‑of‑scope
+- Full stdlib, dynamic plugin matrix, performance tuning beyond correctness.
+
+Deliverables
+- hakorune‑frozen (last Rust‑built) produces hakorune‑new via AOT.
+- Tiny program AOT canary (return/binop/if) builds and runs (rc/last line parity).
+- Docs: AOT pipeline, runtime lib spec, env toggles, known limits.
+
+Refs
+- guides/aot-build.md
+
+Risks/Notes
+- Runtime surface must be minimal and stable; Map remains plugin‑only unless a tiny host path is added for AOT.
+- Prefer harness (ny‑llvmc) for IR/object flow to avoid widening Rust scope (freeze honored).