From c55f9d36891b0bebb544212769f5707fad6bf087 Mon Sep 17 00:00:00 2001
From: Selfhosting Dev <selfhost@example.invalid>
Date: Fri, 19 Sep 2025 22:39:04 +0900
Subject: [PATCH] docs(phase-17): add LoopForm Self-Hosting phase with
 schedule/design/guide; link from AGENTS\n\n- New:
 docs/development/roadmap/phases/phase-17-loopform-selfhost/{README,SCHEDULE,loopform-design}.md\n-
 Guide: docs/guides/loopform.md\n- AGENTS: link phase-17 + loopform guide\n

---
 AGENTS.md                                     |  2 +
 .../phase-17-loopform-selfhost/README.md      | 28 +++++++++++
 .../phase-17-loopform-selfhost/SCHEDULE.md    | 44 +++++++++++++++++
 .../loopform-design.md                        | 49 +++++++++++++++++++
 docs/guides/loopform.md                       | 32 ++++++++++++
 5 files changed, 155 insertions(+)
 create mode 100644 docs/development/roadmap/phases/phase-17-loopform-selfhost/README.md
 create mode 100644 docs/development/roadmap/phases/phase-17-loopform-selfhost/SCHEDULE.md
 create mode 100644 docs/development/roadmap/phases/phase-17-loopform-selfhost/loopform-design.md
 create mode 100644 docs/guides/loopform.md

diff --git a/AGENTS.md b/AGENTS.md
index 2b38ddd7..f5dbcfe2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -73,6 +73,8 @@ Docs links（開発方針/スタイル）
 - Template → Macro 統合方針: `docs/guides/template-unification.md`
 - User Macros（MacroBox/Phase 2）: `docs/guides/user-macros.md`
 - Macro capabilities (io/net/env): `docs/reference/macro/capabilities.md`
+- LoopForm ガイド: `docs/guides/loopform.md`
+- Phase‑17（LoopForm Self‑Hosting & Polish）: `docs/development/roadmap/phases/phase-17-loopform-selfhost/`
  - MacroBox（ユーザー拡張）: `docs/guides/macro-box.md`
   - MacroBox in Nyash（設計草案）: `docs/guides/macro-box-nyash.md`
 
diff --git a/docs/development/roadmap/phases/phase-17-loopform-selfhost/README.md b/docs/development/roadmap/phases/phase-17-loopform-selfhost/README.md
new file mode 100644
index 00000000..6e5b8a49
--- /dev/null
+++ b/docs/development/roadmap/phases/phase-17-loopform-selfhost/README.md
@@ -0,0 +1,28 @@
+# Phase 17 — LoopForm Self‑Hosting & Polish
+
+Status: planning
+
+Purpose
+- Freeze済みのコア仕様を維持しつつ、Nyash側（ユーザーマクロ＋標準ライブラリ）で LoopForm を先に実装し、ループの正規化を言語レベルで確立する。
+- Rust側は既存MIR/LLVMの整流を活用（PHI先頭グループ化の不変条件を活かす）。
+- 実アプリ/自己ホストで磨き込みを進め、言語としての使い心地を上げる。
+
+Scope
+- LoopForm（while→キャリア正規化）のユーザーマクロ実装とガイド。
+- 代表スモーク/ゴールデンの追加（PyVM/LLVMの一致）とPHI健全性チェックの拡充。
+- Docsの整備（設計・ガイド・運用ポリシー）。
+
+Out of Scope（凍結遵守）
+- Rust側の大規模なIR変更やバックエンド機能追加はしない（必要最小限のバグ修正のみ）。
+- 仕様変更は重大不具合を除き行わない。
+
+Guardrails（シンプルさ維持）
+- Small‑by‑default: 既定は簡素、プロファイルで拡張。
+- ヒューリスティック禁止: 明示登録とAST検出のみ。
+- バグは点修正、Docs/テストは積極整備。
+
+Docs
+- guides/loopform.md（利用者向け）
+- loopform-design.md（設計詳細）
+- SCHEDULE.md（開発予定表）
+
diff --git a/docs/development/roadmap/phases/phase-17-loopform-selfhost/SCHEDULE.md b/docs/development/roadmap/phases/phase-17-loopform-selfhost/SCHEDULE.md
new file mode 100644
index 00000000..daa163ed
--- /dev/null
+++ b/docs/development/roadmap/phases/phase-17-loopform-selfhost/SCHEDULE.md
@@ -0,0 +1,44 @@
+# Phase 17 — 開発予定表（LoopForm Self‑Hosting & Polish）
+
+期間目安: 4週間（総量は実アプリ進行に合わせて調整）
+
+Week 1 — LoopForm MVP（while, break/continue無し）
+- 目標: whileループを“キャリア（タプル）”へ正規化するユーザーマクロを実装（Nyash/PyVM）。
+- 成果物:
+  - apps/macros/examples/loop_normalize_macro.nyash（MVP）
+  - ゴールデン: while基本/2変数キャリア/更新式の正規化
+  - スモーク: selfhost-preexpand で自動適用→PyVM/LLVMの一致
+- 受け入れ基準:
+  - ループヘッダのPHIが先頭グループ化され、空PHIが存在しない
+  - 代表ケースでPyVM/LLVMの出力一致
+
+Week 2 — break/continue 対応＋キャリア自動抽出
+- 目標: ループ内のbreak/continueを LoopForm の構造に沿って安全に配置。更新対象変数の集合からキャリア自動推定。
+- 成果物:
+  - マクロ拡張: break/continue/ネストの最小対応
+  - ゴールデン: break/continue混在、未更新変数保持
+- 受け入れ基準:
+  - 分岐経路の合流でキャリアが常にwell‑typed
+  - 変数の外側スコープ値が期待通り
+
+Week 3 — for/foreach（限定）＋設計ドキュメント深掘り
+- 目標: for/foreach を while へ前処理→LoopFormへ正規化。
+- 成果物:
+  - 追加パターン: for (init; cond; step) / foreach (x in xs)
+  - ドキュメント: loopform-design.md（制約/限界/今後のMIR 4命令案）
+- 受け入れ基準:
+  - for/foreachの代表ケースで一致
+
+Week 4 — Polishing & 実アプリ適用
+- 目標: 実アプリ/自己ホストにLoopFormを適用して安定運用。
+- 成果物:
+  - スモーク/ゴールデン拡充、CIゲート最小化（fast/min）
+  - ガイド更新（guides/loopform.md）
+- 受け入れ基準:
+  - 実アプリの主要ユースケースが緑
+
+リスク/対策
+- 複雑なネスト/例外: MVPでは簡略（try/finallyとの相互作用は先送り）→ドキュメントに制約明記
+- 性能: コンパイル時のみの変換負荷。実行性能はMIR/LLVMへ委譲→ベンチで観測
+- 仕様逸脱: 凍結遵守。必要時は限定的なDocs変更で表現
+
diff --git a/docs/development/roadmap/phases/phase-17-loopform-selfhost/loopform-design.md b/docs/development/roadmap/phases/phase-17-loopform-selfhost/loopform-design.md
new file mode 100644
index 00000000..c7348070
--- /dev/null
+++ b/docs/development/roadmap/phases/phase-17-loopform-selfhost/loopform-design.md
@@ -0,0 +1,49 @@
+# LoopForm Design — Macro‑Driven Loop Normalization
+
+Goal
+- ループで発生する「変数キャリア（loop‑carried values）」を Nyash のユーザーマクロで前段正規化し、MIR/LLVM側は素直に最適化可能な形にする。
+
+Key Idea
+- ループ状態（複数変数）をタプル（または専用Box）に束ねて“1個の搬送値（carrier）”として扱う。
+- ループのヘッダで φ は常に“1つのタプル”にだけ付与される → PHIグルーピングの不変が自動で満たされる。
+
+Normalization Pattern（whileのMVP）
+```
+// input
+// i=0; sum=0; while (i<n) { sum = sum + a[i]; i = i + 1 }
+
+// expanded
+let __car0 = (i, sum);
+head:
+  let (i, sum) = __car_phi;
+  if !(i < n) goto exit;
+  let __car1 = (i + 1, sum + a[i]);
+  __car_phi = φ(__car0, __car1);
+  goto head;
+exit:
+  let (i, sum) = __car_phi;
+```
+
+Break/Continue（Week2）
+- continue: “次のキャリア”を構築して head へ遷移。
+- break: 現キャリアで exit へ遷移。
+- ネスト時: 内側ループのcarrierと外側スコープの分解を明示する（名称はgensym）。
+
+for/foreach（Week3）
+- for (init; cond; step) は init→while(cond){ body; step } へ前処理後、同様に正規化。
+- foreach は IteratorBox（MVP）経由の while 形式へ前処理。
+
+Constraints / Notes
+- try/finally/throw との相互作用はMVPでは未対応（将来ガイドで制約を明記）。
+- キャリア自動抽出: 本体で再代入される変数集合を候補とし、ループ外で参照されるものを優先収集。
+- 衛生: MacroCtx.gensym で __car_phi/__carK などの一意名を生成。
+
+Integration
+- ユーザーマクロ: `apps/macros/examples/loop_normalize_macro.nyash`
+- 事前展開: selfhost‑preexpand auto（PyVM限定）で適用
+- 検証: macro‑golden + LLVM PHI健全性スモーク（空PHIなし/先頭グループ化）
+
+Future Work（先の先）
+- MIRに LoopHeader/LoopLatch/LoopContinue/LoopExit の4命令を導入した正規形を検討（最適化/解析の高速化）。
+- Boxベースの LoopState/Carrier の型体系を整理（型推論との接続）。
+
diff --git a/docs/guides/loopform.md b/docs/guides/loopform.md
new file mode 100644
index 00000000..ba46826a
--- /dev/null
+++ b/docs/guides/loopform.md
@@ -0,0 +1,32 @@
+# LoopForm ガイド — ループ正規化（ユーザーマクロ）
+
+目的
+- while/for/foreach を Nyash のユーザーマクロで“キャリア（タプル）”に正規化し、MIR/LLVMにとって最適化しやすい形へ落とし込む。
+
+使い方（予定）
+- マクロ登録（例）:
+```
+export NYASH_MACRO_ENABLE=1
+export NYASH_MACRO_PATHS=apps/macros/examples/loop_normalize_macro.nyash
+```
+- 自己ホスト前展開（auto）を利用して、parse直後にLoopForm展開を有効化（PyVM環境）。
+
+正規化の考え方
+- ループで更新される変数群をタプルに束ね、ヘッダに“1個のφ”を置く。
+- break/continue は“次キャリア”または“現キャリア”で遷移し、一貫した合流点を保つ。
+
+対応状況（MVP→順次拡張）
+- Week1: while（break/continue無し）
+- Week2: break/continue/ネスト最小対応、キャリア自動抽出
+- Week3: for/foreach（限定）
+
+制約（MVP）
+- try/finally/throwとの相互作用は未対応。例外は後続フェーズで設計を明記。
+
+検証
+- macro‑golden（展開後ASTのゴールデン）
+- LLVM PHI健全性スモーク（空PHI無し、先頭グループ化）
+
+参考
+- docs/development/roadmap/phases/phase-17-loopform-selfhost/
+