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)

Read this skill + read_skill bareos-code-change + read_skill docs-contract-update.
Read the current state of Batch C (or the target Stream) in docs/reference/feature-roadmap.md.
Read developer-guide/kernel-program.md (environment hooks, acceptance criteria, Wasm notes, traceability).
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).
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/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)

"kernel-program proc schema 3 + programVersion 3 bump (minimal adjunct fields)"
"new operatorSketch: bareOsEmitKernelProgramOperatorHint"
"Batch C table + verify-kernel-program-roadmap-table.mjs v2 (support for 300 items)"
"kernel.ext.d 'provides' semver field + resolution in resolver"
"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.

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:

cd /Users/raven/dev/pearcli/holepunch-repos/holepunchto_repos/<relevant-bare-foo>
Read its README + main entry point.
Check how the current OS already uses it (grep in packages/bare-os-booter/lib/ and packages/bare-os-coreutils/src/).
Only then design the Batch C item / extension.
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.

8.6 KiB Raw Blame History