bare-operating-system/kernel/share/agent-workspace/skills/kernel-program-extension/SKILL.md

name, version, description, tags, requires

name	version	description	tags	requires
kernel-program-extension	1.0.0	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.	kernel governance roadmap batch-c extension	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.