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

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

@@ -0,0 +1,7 @@
+- [x] SSOT normalize policy documented and enforced (plugins=ON vs OFF)
+- [x] Builder effects defaulted; mutating calls are not DCE’d
+- [x] JSON emit order: single‑pass; no def‑use inversions
+- [x] Core mir_call: positive/negative coverage + stable tags
+- [x] Gate‑C parity: file/pipe × plugins ON/OFF (quiet+rc)
+- [x] Minimal self‑host smoke green (lang→JSON→Core)
+- [x] Docs updated (bootstrap profile, toggles, invariants)

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

@@ -0,0 +1,34 @@
+# Phase‑20.28 — Claude Handoff Spec
+
+Scope
+- Lock down SSOT normalize policy; enforce in runner + interpreter.
+- Harden Builder/Optimizer (effects and order) to avoid DCE/reorder bugs.
+- Expand Core mir_call coverage (Array/String day‑1); Map remains plugin‑only.
+- Gate‑C parity (file/pipe × plugins ON/OFF) with quiet/rc symmetry.
+- Add a minimal self‑host smoke.
+
+Work Items
+1) Normalize policy
+- Runner (Gate‑C final fallback): only normalize Method/ModuleFunction → Extern when `allow_gate_c_plugins=true`.
+- Interpreter (handle_call/Method): when `plugins_disabled()`, skip static/runtime extern routing and use `execute_method_call` directly.
+- Doc a decision table for SSOT (plugins=ON/OFF).
+
+2) Builder/Optimizer
+- Ensure JSON carries effects for mutating calls; when absent, default as WRITE.
+- Emit single‑pass JSON preserving MIR order; remove any postponed Copy emission.
+- Canaries: if‑diamond + set→compare dependency.
+
+3) Core mir_call
+- Positive coverage: Array get/set/push/pop/size via HostSlot/Plugin; ring0(Array) only as last resort.
+- String primitives: length/substring/indexOf/lastIndexOf/replace — bounds checks + stable tags.
+- Negative coverage: Closure callee; bad receiver; missing args.
+
+4) Gate‑C parity + bootstrap
+- file/pipe × plugins ON/OFF — assert quiet/noise and rc consistency.
+- Add `docs/guides/selfhost-bootstrap.md` with env toggles and step‑by‑step.
+- Add minimal self‑host smoke that compiles a tiny program via lang→JSON→Core.
+
+Acceptance
+- All new canaries green; no regression in existing quick/core suite.
+- Docs updated; toggles clearly listed with defaults and aliases.
+

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

@@ -0,0 +1,32 @@
+# Phase‑20.28 — Execution Plan
+
+Milestones
+
+1) Normalize policy (SSOT)
+- Define when Method/ModuleFunction → Extern applies.
+  - plugins=ON: apply SSOT mapping; prepend receiver for Method forms.
+  - plugins=OFF: do not normalize Method/Constructor; let method_router/builtin/ring0 run.
+- Document the decision table and update Gate‑C paths accordingly.
+
+2) Builder/Optimizer hardening
+- Add default effects for mutating calls when JSON omits them (prevent DCE of set/delete/push/pop).
+- Ensure single‑pass emit order for basic blocks (no Copy def‑use inversion).
+- Verify with canaries: if‑diamond, phi, and set→compare dependency.
+
+3) Core mir_call coverage
+- Positive: Array(Map backed host‑slot)/String day‑1 surface; keep Map plugin‑only.
+- Negative: Unsupported callee types (Closure), missing args, bad receiver — stable tags.
+- Expand extern_adapter handlers to prefer HostSlot/Plugin, then ring0(Array only), else Fail‑Fast.
+
+4) Gate‑C parity and profile
+- file/pipe × plugins ON/OFF: quiet/noise and rc mapping symmetry.
+- Bootstrap profile doc: deterministic toggles, plugin policy (force/auto), using/macro guards.
+
+5) Smokes and docs
+- Add minimal self‑host smoke that compiles a tiny program via lang → JSON → Core.
+- Update docs: normalize policy, effects/order guarantees, bootstrap instructions.
+
+Nice‑to‑have (stretch)
+- Reduce duplicate fallbacks by funnelling array ring0 calls through one thin helper.
+- Add jq/awk mini‑validator to check def‑before‑use in canary JSON.
+

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

@@ -0,0 +1,23 @@
+# Phase‑20.28 — Self‑Host Bootstrap (Core + Builder)
+
+Purpose
+- Move from “Core bring‑up + ring0(Array minimal)” to a minimal, repeatable self‑host bootstrap loop: lang compiler emits MIR(JSON v0) that the VM Core executes, under a stable set of rules (effects/order/normalize).
+
+In‑scope (what we complete in this phase)
+- Core mir_call coverage (positive/negative) for day‑1 collections and strings; stable tags for unsupported.
+- Builder/Optimizer: effect hints and single‑pass emit order guarantees for mutating calls (set/push/pop/delete, etc.).
+- Normalize policy (SSOT): When plugins=OFF, do not force Method→Extern; honor Method/Constructor so ring0/builtin can operate. When plugins=ON, canonicalize to Extern as per SSOT.
+- Gate‑C parity: file/pipe × plugins ON/OFF — quiet output and rc mapping symmetry.
+- Minimal bootstrap profile (env/docs): the exact toggles for deterministic self‑host runs.
+
+Out‑of‑scope
+- Full language coverage or full std library. We target the smallest viable loop and expand next.
+- Performance tuning beyond basic correctness.
+
+Why split now
+- Phase‑20.27 finalized Core routing and added ring0(Array) minimal semantics. This phase focuses on closing the JSON→Core loop end‑to‑end for self‑host and stabilizing builder effects/order + normalize policy to avoid drift.
+
+Deliverables
+- Green canaries for Core mir_call (positive/negative), Gate‑C parity, and a small self‑host bootstrap smoke.
+- Docs: normalize policy, effects/order guarantees, bootstrap profile.
+