scopebox: add design guide; scaffold no-op scope/defer macro; add MIR hint plan to CURRENT_TASK

CURRENT_TASK.md

@@ -55,6 +55,7 @@ Next (short)
 - LLVM IR hygiene for LoopForm cases — PHI at block head, no empty PHIs (smoke)
 - Docs: enrich `docs/guides/loopform.md` with carrier examples and JSON builder snippets.
 - If/Match normalization pass: canonical If join with single PHI group and Match→If‑chain (scrutinee once, guard fused), expression results via join var.
+- ScopeBox (compile-time meta): design + docs; no-op macro scaffold; MIR hint names (no-op) and plan for zero-cost stripping.
 
 Action Items (next 48h)
 - [x] Enable sugar by default (array/map literals)
@@ -62,6 +63,7 @@ Action Items (next 48h)
 - [x] Loop simple/two‑vars goldens with normalization
 - [ ] LoopForm MVP‑2: two‑vars carrier safe normalization + tests/smokes
 - [ ] LLVM PHI hygiene smoke on LoopForm cases
+- [ ] ScopeBox docs + macro scaffold (no-op) + MIR hint type sketch
 
 ## Phase‑16 Outlook
 - MacroCtx (gensym/report/getEnv) and capabilities mapped to `nyash.toml`.

apps/macros/examples/scope_defer_macro.nyash

@@ -0,0 +1,16 @@
+// scope_defer_macro.nyash
+// MVP scaffold: detect @scope/@defer style markers in AST JSON (string) and keep identity.
+// Future: attach scope attrs to blocks and emit MIR hints in lowering.
+
+static box MacroBoxSpec {
+  name() { return "ScopeDeferScaffold" }
+
+  expand(json, ctx) {
+    // For now, return input as-is. This keeps behavior unchanged and allows
+    // us to enable/disable the macro without risk. Future versions will:
+    //  - parse attributes/comments/markers to attach scope metadata
+    //  - leave semantic code intact (zero-cost in release)
+    return json
+  }
+}
+

docs/guides/scopebox.md

@@ -0,0 +1,39 @@
+# ScopeBox（コンパイル時メタ）設計ガイド
+
+目的
+- スコープ境界・defer・capabilities を“箱（Box）”のメタとして表現しつつ、最終的な実行物ではゼロコストにする。
+- LoopForm（ループのみキャリア整形）と責務分離し、If/Match は合流点正規化（join変数＋単一PHI群）に限定する。
+
+基本方針
+- ScopeBox は“消える箱”。AST/マクロ段階で Block に属性を付与し、MIR ではヒントとして解釈、IR では完全に剥がす。
+- ループを伴わないスコープを LoopForm に持ち込まない（0回ループ化はしない）。
+
+属性とヒント（MVP）
+- AST（マクロ内部表現）
+  - Block.attrs.scope: { id, name, caps?: {io,net,env}, defer?: [Call…], diag?: {...} }
+  - 備考: 現段階では属性はマクロ内で保持するだけ。MIR 降下時にヒントへ写すのが目標。
+- MIR（ヒントのみ／構造不変）
+  - hint.scope_enter(id) / hint.scope_leave(id)
+  - hint.defer(list) ・・・ 静的展開（cleanup合流）に用いる
+  - hint.join_result(var) ・・・ If/Match の合流結果を明示
+  - hint.loop_carrier(vars...) ・・・ ループヘッダで同一PHI群に導く
+  - hint.no_empty_phi（検証）
+- IR（Release）
+  - すべての hint は生成前に剥離。追加命令は一切残らない。
+
+パイプライン
+1) Parse → Macro（If/Match 正規化、Scope 属性付与）
+2) LoopForm（while/for/foreach のみ、キャリア整形）
+3) Resolve → MIR Lower（ヒント埋め、defer静的展開）
+4) 検証（PHI先頭／空PHI無し）→ ヒント剥離 → Backend
+
+受け入れ基準（Release）
+- IR に scope/hint 名が一切出現しない。
+- LoopForm ケースはヘッダ先頭に PHI がまとまり、空PHI無し。
+- If/Match 式は join 変数 1 個で収束（空PHI無し）。
+
+今後の予定（短期）
+- マクロ: @scope/@defer 記法のスキャフォールド → AST 属性付与（挙動は現状どおり、構造変更無し）。
+- MIR: hint.* の型と注入ポイント定義（降下部のスケルトン、既定は no-op）。
+- スモーク: IR に scope/hint 名が残らないこと、PHI 健全性が保たれることを確認。
+