feat: POSIX/Holepunch plan — proc contracts, shell, vault audit, docs, tests

- Docs: kernel-program truth, PLACEHOLDER_BASELINE, POSIX_DECLARED_PROFILE,
  env appendix (BARE_OS_SHELL_PIPEFAIL, BARE_OS_WASM_KERNEL), package-bare-os-booter
- Booter: syscalls.json fd model, process_table exitStatusModel, shell pipeline
  exit status + kernel-runner script-error path, mirror mounts test + handbook
- Seeder: corestore_snapshot proc alignment test; hyperswarm ^4.17.0; kernel mirror sync
- Vault: vault_save audit after saveVaultToDrive; split bare-os-vault-rotation-audit.js
- Contract: protomux/hyperswarm lock fixture + test; IPC stats ipcBackpressure test
- Coreutils: XCU tests, bare-cron man seed, ACL/xattr metadata path test
- Tooling: kernel-microbench + release-gate fixture doc; ADR 002 WASM compile hook
- Changelog/ctx d.ts and dependency/lockfile updates as needed

developer-guide/adr/002-wasm-kernel-compile-hook.md

@@ -0,0 +1,27 @@
+# ADR 002: Feature-gated WASM compile hook (`ctx.bareOsWasmKernelCompile`)
+
+## Status
+
+Accepted (2026-04-04)
+
+## Context
+
+Operators asked for a **bounded** path to validate WebAssembly modules in the same runtime that runs the kernel, without pulling **Node.js** builtins into booter sources or silently loading foreign code.
+
+## Decision
+
+- Expose **`ctx.bareOsWasmKernelCompile(buf, opts?)`** only when the host sets **`BARE_OS_WASM_KERNEL=1`** (or **`true`**), copied into session **`shellEnv`** like other passthrough keys.
+- Implementation calls **`WebAssembly.compile`** on a **size-capped** **`Uint8Array`** (default max **512 KiB**; override via **`opts.maxBytes`**). **No instantiation**, **no imports**, and **no execution** — compile-only probe suitable for static validation and export-name listing when the engine exposes **`WebAssembly.Module.exports`**.
+- Code lives in **`packages/bare-os-booter/lib/bare-os-wasm-kernel.js`** and uses **`globalThis`** only (Bare/V8).
+
+## Consequences
+
+- **Security:** Mis-toggling **`BARE_OS_WASM_KERNEL`** only enables compilation CPU work within caps; it does **not** grant syscall bridges. Full guest loaders remain out of scope for this ADR.
+- **Optional dep:** **`bare-vm`** remains an optional package for future **instantiation** work; this ADR does not require it on the compile path.
+- **Docs:** Environment appendix lists **`BARE_OS_WASM_KERNEL`**; [POSIX declared profile](../../docs/architecture/POSIX_DECLARED_PROFILE.md) remains the normative “honest POSIX” surface.
+
+## Related
+
+- **`docs/architecture/POSIX_DECLARED_PROFILE.md`**
+- **`docs/reference/environment-and-posix-appendix.md`**
+- **`packages/bare-os-booter/CHANGELOG.md`** (ctx **1.33.0**)

developer-guide/adr/README.md

@@ -1,6 +1,6 @@
 # Architecture decision records (ADRs)
 
-Use [000-template.md](000-template.md) for new decisions. Number sequentially (`001-…`, `002-…`).
+Use [000-template.md](000-template.md) for new decisions. Number sequentially (`001-…`, `002-…`). See [002-wasm-kernel-compile-hook.md](002-wasm-kernel-compile-hook.md).
 
 ADRs capture **contract and behavior** choices that are expensive to reverse: protocol fields, capability semantics, boot policy keys, and deprecation windows.