From e912ef9134f001acd22c2c271a4c969422a85046 Mon Sep 17 00:00:00 2001
From: nyash-codex <codex@nyash.local>
Date: Sun, 14 Dec 2025 05:27:39 +0900
Subject: [PATCH] =?UTF-8?q?docs(phase131):=20SSOT=E6=95=B4=E5=82=99=20-=20?=
 =?UTF-8?q?VM=E5=85=A5=E5=8F=A3/env=20var/=E6=AC=A1=E3=81=AE=E5=85=A5?=
 =?UTF-8?q?=E5=8F=A3=E3=82=921=E7=AE=87=E6=89=80=E3=81=AB=E5=9B=BA?=
 =?UTF-8?q?=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 131 SSOT 整備完了:

1) VM Box 解決の入口SSOT（phase131-2-box-resolution-map.md）
   - 📍 入口3行を先頭に追記（handle_new_box/UnifiedRegistry/BoxFactoryRegistry）
   - NYASH_VM_FAST を bench/profile-only 特例と明記

2) 環境変数のSSOTを1箇所へ（environment-variables.md）
   - ## LLVM Build Pipeline セクション新設（14変数）
   - phase87 の Environment Variables セクションを参照リンクに置き換え
   - 重複表を削除、SSOTドキュメントへの導線確立

3) 次の開発の入口を明確化（CURRENT_TASK.md）
   - P1（Loop Canonicalizer）: 🔶 設計待ち（外部検討中）
   - P2（JoinIR / Selfhost depth-2）: ✅ 実装可能
   - 次に触るSSOTを1行で指定:
     - Loop系: joinir-architecture-overview.md
     - VM Box系: phase131-2-box-resolution-map.md

Impact:
- 迷子防止: 各領域のSSOTが1行で分かる
- 重複削減: env var 表を environment-variables.md に集約
- 状態明確化: P1/P2 の「設計待ち/実装可能」が一目瞭然

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CURRENT_TASK.md                               | 17 +++++-
 .../main/phase131-2-box-resolution-map.md     |  7 +++
 .../main/phase87-selfhost-llvm-exe-line.md    | 60 ++-----------------
 docs/reference/environment-variables.md       | 44 ++++++++++++++
 4 files changed, 71 insertions(+), 57 deletions(-)

diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md
index b8738122..2949a7b9 100644
--- a/CURRENT_TASK.md
+++ b/CURRENT_TASK.md
@@ -50,20 +50,31 @@
 - 読み始め導線が `01-JoinIR-Selfhost-INDEX.md` から辿れる
 - `10-Now.md` と `CURRENT_TASK.md` は “最新の入口” として機能する（詳細は要約へ）
 
-### P1: Loop Canonicalizer の設計（docs-only、外部検討待ち）
+### P1: Loop Canonicalizer の設計（設計待ち - 外部検討中）
 
-**目的**: ループ形状の組み合わせ爆発を抑えるための “前処理パス” を設計し、SSOT を定める
+**状態**: 🔶 設計中（ChatGPT Pro と詰めている）
+
+**目的**: ループ形状の組み合わせ爆発を抑えるための "前処理パス" を設計し、SSOT を定める
+
+**次に触るSSO**:
+- Loop系の設計: `docs/development/current/main/joinir-architecture-overview.md`
 
 注意:
 - 実装は急がず、設計（SSOT）を先に固める
 - 既定挙動は変えない（dev-only で段階投入する）
 
-### P2: JoinIR / Selfhost depth-2 の前進（Phase 91 候補）
+### P2: JoinIR / Selfhost depth-2 の前進（実装可能 - Phase 91 候補）
+
+**状態**: ✅ 実装可能
 
 目的:
 - JsonParserBox の残り複合ループを JoinIR 対応する。
 - または selfhost .hako コンパイラの他部分（Lexer/ASTBuilder 等）で JoinIR 適用範囲を拡大する。
 
+**次に触るSSOT**:
+- Loop系: `docs/development/current/main/joinir-architecture-overview.md`
+- VM Box系: `docs/development/current/main/phase131-2-box-resolution-map.md`
+
 やること（設計→実装の順）:
 1. 候補ループの抽出（JsonParserBox or Lexer/ASTBuilder）
 2. Pattern 判定（Pattern 1-4 のいずれか、または新 Pattern 提案）
diff --git a/docs/development/current/main/phase131-2-box-resolution-map.md b/docs/development/current/main/phase131-2-box-resolution-map.md
index c66def35..45826a37 100644
--- a/docs/development/current/main/phase131-2-box-resolution-map.md
+++ b/docs/development/current/main/phase131-2-box-resolution-map.md
@@ -1,5 +1,12 @@
 # Phase 131-2: Box Resolution Mapping - 現状 vs 理想
 
+## 📍 VM Box 解決の入口SSOT（迷ったらここ）
+
+- **MIR NewBox 受付**: `src/backend/mir_interpreter/handlers/boxes.rs` の `handle_new_box()`
+- **Box 登録管理**: `src/runtime/unified_registry.rs` の `UnifiedBoxRegistry`
+- **Factory 実装**: `src/box_factory/mod.rs` + Plugin は `src/runtime/box_registry.rs` の `BoxFactoryRegistry`
+- **NYASH_VM_FAST**: bench/profile-only 特例（既定OFF、本番では使わない）
+
 ## 🗺️ 現状マップ（VM Backend）
 
 ```
diff --git a/docs/development/current/main/phase87-selfhost-llvm-exe-line.md b/docs/development/current/main/phase87-selfhost-llvm-exe-line.md
index 7680069a..32518f98 100644
--- a/docs/development/current/main/phase87-selfhost-llvm-exe-line.md
+++ b/docs/development/current/main/phase87-selfhost-llvm-exe-line.md
@@ -95,61 +95,13 @@ NYASH_LLVM_COMPILER=crate NYASH_LLVM_EMIT=exe \
 
 ## Environment Variables Reference
 
-### Control Variables
+環境変数の一覧は [`docs/reference/environment-variables.md`](../../reference/environment-variables.md#llvm-build-pipeline) の「LLVM Build Pipeline」セクションを参照してください。
 
-These environment variables control the build pipeline behavior:
-
-| Variable | Default | Purpose | Example |
-|----------|---------|---------|---------|
-| `NYASH_BIN` | `./target/release/hakorune` | Path to hakorune binary | `NYASH_BIN=/custom/path/hakorune` |
-| `NYASH_LLVM_COMPILER` | `harness` | Compiler mode: `harness` or `crate` | `NYASH_LLVM_COMPILER=crate` |
-| `NYASH_LLVM_FEATURE` | `llvm` | LLVM feature flag for cargo build | `NYASH_LLVM_FEATURE=llvm-inkwell-legacy` |
-| `NYASH_LLVM_OBJ_OUT` | `target/aot_objects/<stem>.o` | Object file output path | `NYASH_LLVM_OBJ_OUT=/tmp/custom.o` |
-| `NYASH_CLI_VERBOSE` | `0` | Enable verbose build output | `NYASH_CLI_VERBOSE=1` |
-
-### Advanced Control Variables
-
-For specialized use cases and debugging:
-
-| Variable | Default | Purpose | Example |
-|----------|---------|---------|---------|
-| `NYASH_LLVM_SKIP_EMIT` | `0` | Skip object generation (use pre-generated .o) | `NYASH_LLVM_SKIP_EMIT=1` |
-| `NYASH_LLVM_ONLY_OBJ` | `0` | Stop after object generation (skip linking) | `NYASH_LLVM_ONLY_OBJ=1` |
-| `NYASH_LLVM_SKIP_NYRT_BUILD` | `0` | Skip Nyash Kernel runtime build | `NYASH_LLVM_SKIP_NYRT_BUILD=1` |
-| `NYASH_LLVM_MIR_JSON` | (auto-generated) | Pre-generated MIR JSON path (crate mode) | `NYASH_LLVM_MIR_JSON=/tmp/mir.json` |
-| `NYASH_LLVM_VALIDATE_JSON` | `0` | Validate MIR JSON schema (crate mode) | `NYASH_LLVM_VALIDATE_JSON=1` |
-| `NYASH_LLVM_EMIT` | `obj` | Emission mode: `obj` or `exe` (crate only) | `NYASH_LLVM_EMIT=exe` |
-| `NYASH_LLVM_NYRT` | `crates/nyash_kernel/target/release` | Nyash Kernel runtime path | `NYASH_LLVM_NYRT=/custom/nyrt` |
-| `NYASH_LLVM_LIBS` | (empty) | Additional link libraries | `NYASH_LLVM_LIBS="-lcustom"` |
-| `NYASH_LLVM_USE_HARNESS` | (auto-set) | Force Python harness usage | `NYASH_LLVM_USE_HARNESS=1` |
-
-### Typical Usage Examples
-
-**Basic build** (all defaults):
-```bash
-tools/build_llvm.sh program.hako -o output
-```
-
-**Verbose debugging**:
-```bash
-NYASH_CLI_VERBOSE=1 tools/build_llvm.sh program.hako -o output
-```
-
-**Use pre-generated object file**:
-```bash
-# Step 1: Generate object via smoke test
-./tools/smokes/v2/run.sh --profile quick --filter 'smoke_obj_*'
-
-# Step 2: Link using existing object
-NYASH_LLVM_SKIP_EMIT=1 NYASH_LLVM_OBJ_OUT=target/aot_objects/existing.o \
-  tools/build_llvm.sh program.hako -o output
-```
-
-**Crate mode with validation**:
-```bash
-NYASH_LLVM_COMPILER=crate NYASH_LLVM_VALIDATE_JSON=1 \
-  tools/build_llvm.sh program.hako -o output
-```
+主要な環境変数（クイックリファレンス）：
+- `NYASH_LLVM_COMPILER`: コンパイラモード (`harness` または `crate`)
+- `NYASH_CLI_VERBOSE=1`: 詳細ビルド出力を有効化
+- `NYASH_LLVM_ONLY_OBJ=1`: オブジェクト生成後に停止
+- その他14変数の詳細は上記SSOTドキュメントを参照
 
 ## Standard Procedure
 
diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
index f8bcf113..1d8445e1 100644
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@@ -84,6 +84,50 @@ NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \
 
 ---
 
+## LLVM Build Pipeline
+
+`tools/build_llvm.sh` で使用される環境変数。詳細は [`phase87-selfhost-llvm-exe-line.md`](../development/current/main/phase87-selfhost-llvm-exe-line.md) を参照。
+
+### Control Variables
+
+| 変数 | デフォルト | 説明 |
+| --- | --- | --- |
+| `NYASH_BIN` | `./target/release/hakorune` | hakorune バイナリのパス |
+| `NYASH_LLVM_COMPILER` | `harness` | コンパイラモード: `harness` または `crate` |
+| `NYASH_LLVM_FEATURE` | `llvm` | LLVM feature flag (`llvm` または `llvm-inkwell-legacy`) |
+| `NYASH_LLVM_OBJ_OUT` | `target/aot_objects/<stem>.o` | オブジェクトファイル出力パス |
+| `NYASH_CLI_VERBOSE` | `0` | 詳細ビルド出力を有効化 |
+
+### Advanced Control Variables
+
+| 変数 | デフォルト | 説明 |
+| --- | --- | --- |
+| `NYASH_LLVM_SKIP_EMIT` | `0` | オブジェクト生成をスキップ（既存 .o 使用） |
+| `NYASH_LLVM_ONLY_OBJ` | `0` | オブジェクト生成後に停止（リンクスキップ） |
+| `NYASH_LLVM_SKIP_NYRT_BUILD` | `0` | Nyash Kernel runtime ビルドをスキップ |
+| `NYASH_LLVM_MIR_JSON` | (auto) | 事前生成 MIR JSON パス (crate mode) |
+| `NYASH_LLVM_VALIDATE_JSON` | `0` | MIR JSON スキーマ検証を有効化 (crate mode) |
+| `NYASH_LLVM_EMIT` | `obj` | 出力タイプ: `obj` または `exe` (crate only) |
+| `NYASH_LLVM_NYRT` | `crates/nyash_kernel/target/release` | Nyash Kernel runtime パス |
+| `NYASH_LLVM_LIBS` | (empty) | 追加リンクライブラリ |
+| `NYASH_LLVM_USE_HARNESS` | (auto) | Python harness 使用を強制 |
+
+### 使用例
+
+```bash
+# 基本ビルド（全デフォルト）
+tools/build_llvm.sh program.hako -o output
+
+# 詳細デバッグ
+NYASH_CLI_VERBOSE=1 tools/build_llvm.sh program.hako -o output
+
+# Crate mode + JSON検証
+NYASH_LLVM_COMPILER=crate NYASH_LLVM_VALIDATE_JSON=1 \
+  tools/build_llvm.sh program.hako -o output
+```
+
+---
+
 ## Selfhost compiler / Ny compiler
 
 | 変数 | デフォルト | 適用経路 | 説明 |