---
name: kernel-program-extension
version: 1.0.0
description: Governed extension of the kernel program (Batch C and beyond) — roadmap tables, verifiers, ADR 001, ctx/proc/policy surface. Use for any new boot phases, /proc/kernel_program entries, operator sketches, or capability word items.
tags: [kernel, governance, roadmap, batch-c, extension]
requires: [read_skill, verification_hints, read_proc_file, read_file]
---

# kernel-program-extension Skill

## When to use
Use for any work that touches the **governed kernel expansion** (Batch C items, new capability word after 11, new boot hooks, kernel.ext.d ordering, operatorSketches, new /proc/bare_os/kernel_program.json fields, or related verifiers and docs).

**Always** start here instead of ad-hoc changes. This is the continuation of the 200-item baseline (A + B) now entering Batch C.

## Before any edit (mandatory order)
1. Read this skill + `read_skill bareos-code-change` + `read_skill docs-contract-update`.
2. Read the current state of **Batch C** (or the target Stream) in `docs/reference/feature-roadmap.md`.
3. Read `developer-guide/kernel-program.md` (environment hooks, acceptance criteria, Wasm notes, traceability).
4. If on a host git checkout, call **`verification_hints`** with the exact paths you plan to touch (including any new verify-*.mjs or skill files).
5. Call `read_proc_file` on `/proc/bare_os/kernel_program.json` (and `/proc/bare_os/features` + `capabilities.json`) in a live session to see the current programVersion / operatorSketches.

## Execution rules
- **Roadmap first**: Add or update the row in the correct Batch C (or Stream) table **before** writing implementation code. Keep the 100-row table format exactly (the `verify-kernel-program-roadmap-table.mjs` counts `| N |` lines).
- **Governance**: New capability word? Follow `developer-guide/adr/001-kernel-feature-bits-governance.md` § "Assigning a new bit" + add the FEATURE* const + stock word + bump only if meaning changes. New major surface → new ADR under developer-guide/adr/.
- **Never hand-edit generated**:
  - kernel/bin/*, kernel/share/man/man.json, kernel/lib/bare/shell-completion.json
  - seeder/kernel/ copy (use maintainer sync scripts after build)
  - posix-dashboard, compatibility-matrix generated sections, ctx client helper, etc.
- **Verifiers you will run** (add steps to your plan):
  - `verify-kernel-program-doc.mjs`
  - `verify-kernel-program-roadmap-table.mjs`
  - `verify-feature-roadmap-paths.mjs`
  - The specific word-N verifier if adding bits
  - Full `npm test` (or at minimum the kernel-program + doc subset) before any PR
- For a new **proc builder** or **ctx.bareOs*** method: copy the exact pattern from a word-11 file (e.g. `bare-os-proc-hypercore-pack-hrpc-lifecycle.js` + emitter in index.js + entry in bare-os-ctx-api.js + .d.ts). Update the programVersion / schema note in kernel-program.md.
- For **agent skills** supporting kernel program work: keep this skill + bareos-code-change in the requires list and update `BARE_AGENT_SKILL_SEED_REL` in `packages/bare-os-coreutils/lib/agent-workspace.js` (the source of truth for seeding).

## Output contract (what you must produce)
- Updated `feature-roadmap.md` table row(s) with status "in progress" or "done — links to PR + verifier".
- Any new `verify-*.mjs` or updates to `scripts/README.md` pretest runbook.
- If ctx or proc surface changed: entry in `packages/bare-os-booter/CHANGELOG.md` (ctx API table) + compatibility-matrix update.
- This skill (or a follow-up task) updated if the workflow improved.
- Clear "Next autonomous step" note for the operator or future agent run.

## Constraints
- Do **not** start implementation until the roadmap row + verification_hints step are complete.
- Batch C items should be small, self-contained, and testable with existing harnesses (`run-bin`, booter test.js, integration smoke, kernel selftest).
- Prefer extending an existing word or adding a pure operator sketch / env hook before inventing a new word-12 (words are expensive — 100-item checklist + verifier + doc sweep).
- Keep AGENTS.md drift guard: never edit SOUL.md or AGENTS.md in the same session as this work unless the task explicitly says to evolve governance rules.

## Example first Batch C items (use these as templates)
1. "kernel-program proc schema 3 + programVersion 3 bump (minimal adjunct fields)"
2. "new operatorSketch: bareOsEmitKernelProgramOperatorHint"
3. "Batch C table + verify-kernel-program-roadmap-table.mjs v2 (support for 300 items)"
4. "kernel.ext.d 'provides' semver field + resolution in resolver"
5. "Wasm kernel bridge syscall surface expansion (posix_fadvise etc. when enabled)"

See the end of Batch B in feature-roadmap.md for the exact table style and the last item that wired the verifier.

## Related skills (read them)
- bareos-code-change
- docs-contract-update
- bare-os-kernel-proc (for reading the live state while designing)
- ctx-api-change (if the extension adds ctx surface)
- proc-node-change (if adding new /proc/bare_os/* nodes)

## Bare / Pear Runtime Constraints (critical — read before writing any guest code)

**Guest code** (anything that runs via `runScriptFromSource`, ends up in `kernel/bin/`, kernel extensions, or user scripts executed by the shell) runs under the **Bare** runtime, **not** Node.js.

**Hard rules** (enforced by CI + boot policy + the runtime itself):
- **Never** use `node:` specifiers (`node:fs`, `node:path`, `node:crypto`, `node:worker_threads`, etc.) in any code that ships in the image or runs as a guest script.
- Use the corresponding **`bare-*`** packages directly (or via the curated `ctx.bare` + import map provided by the manifest).
- The authoritative local source for these replacements lives at the user's clone: `/Users/raven/dev/pearcli/holepunch-repos/holepunchto_repos/` (the value of `BARE_OS_HOLEPUNCH_CLONES_ROOT`).

**Key direct replacements** (most commonly needed):
- `node:fs` / `fs` → `bare-fs`
- `node:path` / `path` → `bare-path`
- `node:crypto` → `bare-crypto`
- `node:worker_threads` → `bare-worker`
- `node:process` → `bare-process`
- `node:net`, `node:dgram`, `node:http`, `node:https`, `node:tls` → the corresponding `bare-*` packages
- `node:module` / `createRequire` → `bare-module` + `bare-module-resolve`
- `node:buffer` → `bare-buffer`
- Timers, events, streams, etc. have `bare-*` equivalents.

**How Bare OS exposes them**:
- Pre-bundled IIFEs live in the image at `/lib/bare/bundles/` (built by `bare-os-bare-libs` from the manifest).
- `ctx.bare` (when enabled) gives runtime access to more (some host-only or native-addon rows).
- The `bare-module-manifest.json` (in booter + image) + `bare-module` resolver provide the import map shimming.
- See `developer-guide/12-bare-modules-and-pear-ecosystem.md`, `developer-guide/node-to-bare-modules.md`, and `kernel/lib/bare/README.md`.

**Host-side booter / seeder code** (the trusted JS implementing VFS, shell, initd, delegates, etc.) runs under Pear/Node and **may** use Node builtins **only** via the conditional imports:
- `import ... from '#host-fs'`
- `import ... from '#host-path'`
- etc.
These are resolved by the package `imports` map. All such files are scanned by `scripts/verify-pear-no-static-node-import.mjs` in pretest.

**When adding new kernel program surface** (new proc nodes, new `bareOs*` methods, new operator sketches, new worker/sandbox features, new crypto usage, etc.):
- If the code runs in the **guest** (most `/bin`, user extensions, scripts in `kernel.d` or `kernel.ext.d`): design against `bare-*` APIs or the existing `ctx` surface. Look at the actual packages in the local clone first.
- If the implementation lives in the **booter** (host side): you can use native Bare addons or Node APIs via the `#host-*` aliases, but any guest-visible API must be carefully bridged.
- New native-heavy features often require updates to the bare catalog, the manifest, and a `bare-os-bare-libs` build + kernel image sync.

**Practical workflow when touching runtime-sensitive areas**:
1. `cd /Users/raven/dev/pearcli/holepunch-repos/holepunchto_repos/<relevant-bare-foo>`
2. Read its README + main entry point.
3. Check how the current OS already uses it (grep in `packages/bare-os-booter/lib/` and `packages/bare-os-coreutils/src/`).
4. Only then design the Batch C item / extension.
5. After changes, run `npm run build -w bare-os-bare-libs` (if manifest touched) + the normal kernel parity steps.

**Reference scripts** (always run when relevant):
- `npm run gen:bare-catalog` / `:check`
- `npm run sync:bare-manifest`
- `npm run audit:holepunch-clones` (uses exactly the clone root above)
- `node scripts/verify-holepunch-clone-drift.mjs`

This section was added during autonomous M1 research against the live local clone. Keep it updated as the ecosystem evolves.