Agent Updates

2026-04-27 01:00:06 -04:00
parent aa81fbff5b
commit 6bc5accb66
63 changed files with 1372 additions and 46811 deletions
@@ -6,6 +6,14 @@
 2. Load latest MEMORY.md + today's memory/YYYY-MM-DD.md
 3. Execute BOOTSTRAP.md tasks

+## Plan → execute → verify → report
+
+For non-trivial work: state a short plan, use tools (prefer runtime_diagnostic_bundle over guessing live state), verify with read_proc_file or logs, then task_complete with a confidence note (what was verified vs assumed).
+
+## Blast radius
+
+Before multi-file edits, note packages, contracts, generated artifacts, and doc trees that must move together (see developer-guide README cheat sheet).
+
 ## Security & Scope Rules (NEVER violate)

 - Only operate inside approved Hyperdrives (system + personal).
@@ -1,3 +1,14 @@
 # MEMORY.md - Long-term Learned Knowledge

 (Agent appends distilled insights here over time)
+
+## Structured ledger (optional)
+
+Append short bullets under dated headings:
+
+- FACT — durable repo or env truth (cite path).
+- CHECK — verifier or npm script that proved something.
+- RISK — unresolved assumption or flaky area.
+- HANDOFF — what the next session should read first.
+
+Daily detail can go in `memory/YYYY-MM-DD.md`; keep MEMORY.md as the rolling summary.
@@ -23,3 +23,15 @@ Disable reasoning/process output with `edit_agent_config` (`show_reasoning=false
 ## /xai-debug

 Validate xAI compatibility settings, stream behavior, reasoning summary visibility, and tool-call handling. Recommend `reasoning_mode=trace` when summaries are absent.
+
+## /verify-hints
+
+Pass `verification_hints` with the paths or topic you are about to edit (host checkout) to list suggested npm/node checks before leaving the agent.
+
+## /diag-bundle
+
+Run `runtime_diagnostic_bundle` once for live `/proc` and resource snapshot before deep P2P or booter debugging.
+
+## Multi-agent handoff (human or tools)
+
+Split work: one pass for repo/doc scout (read_skill + read_man_page), one for verification hints and smallest test lane, one for summarizing risks. Hand off structured JSON notes in MEMORY.md rather than repeating full logs.
@@ -47,3 +47,14 @@ The agent has access to modular **skills** under `~/.agent/workspace/skills/` (a
 - A **compact** list of skill ids + short descriptions is included in the system prompt.
 - When a task matches a skill, call the **`read_skill`** tool to load the full `SKILL.md`, then follow it exactly.
 - Prefer using skills over reinventing workflows.
+
+## Host-checkout helpers (git workspace on the machine)
+
+When the user is editing the Bare OS repo on the host (not only inside this guest):
+
+- **`verification_hints`** — suggests `npm run …` / `node scripts/verify-*.mjs` from topic keywords or paths; does not run them here.
+- At the repo root, **`npm run agent:path-hints`** takes path arguments; **`npm run agent:holepunch-index`** dumps a JSON index of local `holepunchto_repos` packages.
+
+## One-shot diagnostics
+
+- **`runtime_diagnostic_bundle`** — ctx API version, resource snapshot if available, and all allowlisted `/proc/bare_os/*` snapshots that exist (bounded).
@@ -0,0 +1,22 @@
+---
+name: bareos-code-change
+description: Generic Bare OS change — contract spine, docs, checks, parity before touching code.
+tags: [bare-os, workflow, governance]
+requires: [read_skill, read_proc_file, verification_hints]
+---
+
+# bareos-code-change
+
+## Before edits
+
+1. Identify contract spine: reference doc under docs/reference or developer-guide, generators in scripts/README.md, verifier names.
+2. Run read_proc_file on /proc/bare_os/features and capabilities.json if behavior depends on runtime bits.
+3. If working from a git checkout on the host, call verification_hints with paths you will touch.
+
+## After edits (host checkout)
+
+Run the smallest check that covers your change; escalate to npm run pretest before push.
+
+## Never
+
+Hand-edit *.generated.ts, posix-dashboard.md, or kernel-extensions-generated-toc without running generators.
@@ -0,0 +1,17 @@
+---
+name: coreutils-command-change
+description: /bin utilities — commands.mjs, build, man JSON, BARE_OS_BIN_API pragma, parity.
+tags: [coreutils, bin, man]
+requires: [read_man_page, verification_hints]
+---
+
+# coreutils-command-change
+
+## Flow
+
+1. packages/bare-os-coreutils/lib/commands.mjs and src/<cmd>.js
+2. man/pages/<cmd>.json
+3. npm run build -w bare-os-coreutils
+4. node scripts/verify-man-coverage.mjs and verify-kernel-seeder-parity when kernel/bin updated
+
+See developer-guide/16-how-to-add-bin-utility.md and 06-extending-bin-coreutils.md.
@@ -0,0 +1,19 @@
+---
+name: ctx-api-change
+description: ctx API semver, types, compatibility matrix, feature bits alignment.
+tags: [ctx, api, semver]
+requires: [read_proc_file, verification_hints]
+---
+
+# ctx-api-change
+
+## Touch list
+
+- packages/bare-os-booter/lib/bare-os-ctx-api.js
+- packages/bare-os-booter/lib/bare-os-ctx.d.ts
+- docs/reference/compatibility-matrix.md
+- packages/bare-os-booter/CHANGELOG.md
+
+## Checks
+
+verification_hints with paths under bare-os-booter; run verify-ctx-api-feature-bits and verify-ctx-dts from repo root.
@@ -0,0 +1,10 @@
+---
+name: docs-contract-update
+description: Documentation changes — canonical source first, link env appendix, pretest generators.
+tags: [docs, contributing]
+requires: [read_man_page]
+---
+
+# docs-contract-update
+
+Follow docs/CONTRIBUTING-DOCS.md: relative links, Mermaid rules, no task lists in normative docs. Version tables live in compatibility-matrix and environment appendix — link, do not duplicate. After edits run npm run pretest or verify-doc-links.
@@ -0,0 +1,14 @@
+---
+name: holepunch-local-mirror
+description: Ground Holepunch APIs in local holepunchto_repos clones before inventing usage.
+tags: [holepunch, hypercore, pear, upstream]
+requires: [read_skill]
+---
+
+# holepunch-local-mirror
+
+Default clone root: ~/dev/pearcli/holepunch-repos/holepunchto_repos (or BARE_OS_HOLEPUNCH_CLONES_ROOT).
+
+For API questions: open that repo’s package.json exports, README, lib/, and test/. Cite paths. On host checkout run npm run agent:holepunch-index > /tmp/index.json for a full package list.
+
+Tier-1 stacks: hypercore, corestore, hyperdrive, hyperswarm, hyperdht, protomux, pear, pear-runtime, bare-runtime, bare-* shims.
@@ -0,0 +1,22 @@
+---
+name: hyperdrive-replication
+description: Hyperdrive replication, MBR, swarm disk — read protocol docs and Holepunch hyperdrive first.
+tags: [hyperdrive, p2p, replication]
+requires: [read_man_page, read_proc_file, runtime_diagnostic_bundle]
+---
+
+# hyperdrive-replication
+
+## Read first (repo)
+
+- handbook/03-protocol-and-disk.md
+- docs/reference/package-bare-os-protocol.md
+- docs/reference/architecture-data-flow.md
+
+## Local mirror
+
+Use holepunchto_repos/hyperdrive and related packages for API examples; cite file paths when adapting code.
+
+## Live state
+
+runtime_diagnostic_bundle plus read_proc allowlisted swarm files; compare with Hyperswarm teardown order in docs/reference/hyperswarm-protomux-teardown.md.
@@ -0,0 +1,17 @@
+---
+name: pear-runtime-debug
+description: Pear dev runs, hoisted node_modules, BARE_OS_PEAR_* — isolate from Node-only booter runs.
+tags: [pear, runtime, booter]
+requires: [read_man_page, runtime_diagnostic_bundle]
+---
+
+# pear-runtime-debug
+
+## Read
+
+- docs/PEAR-RUN.md
+- users-manual/03-running-seeder-and-booter.md (ensure-pear-node-modules, npm run os:seeder / os:booter from repo root)
+
+## Debug
+
+Compare pear run --dev with node index.js when bugs are Pear-only. runtime_diagnostic_bundle for live proc snapshot.
@@ -0,0 +1,10 @@
+---
+name: proc-node-change
+description: Add or change /proc/bare_os nodes — VFS, schema, privacy, tests.
+tags: [proc, vfs, schema]
+requires: [read_skill, read_proc_file]
+---
+
+# proc-node-change
+
+Follow developer-guide/15-how-to-add-proc-node.md end to end: booter wiring, snapshot shape, schema under docs/schemas when applicable, redact secrets, add tests in bare-os-booter where appropriate.
@@ -0,0 +1,19 @@
+---
+name: protomux-channel
+description: Protomux channels and compact-encoding messages — align with bare-os-protocol and teardown order.
+tags: [protomux, protocol, wire]
+requires: [read_man_page, read_proc_file]
+---
+
+# protomux-channel
+
+## Read first
+
+- packages/bare-os-protocol/lib/channel.js
+- packages/bare-os-protocol/lib/messages.js
+- docs/reference/package-bare-os-protocol.md
+
+## Rules
+
+- Channel name and message IDs must match seed channel setup.
+- Teardown: swarm before drives when touching booter lifecycle (see hyperswarm-protomux-teardown.md).
@@ -0,0 +1,17 @@
+---
+name: seed-rpc-change
+description: Seed RPC registry and channel handlers — no drift from seed-rpc-methods.js.
+tags: [seed-rpc, protocol, rpc]
+requires: [read_man_page, verification_hints]
+---
+
+# seed-rpc-change
+
+## Order
+
+1. packages/bare-os-protocol/lib/seed-rpc-methods.js
+2. packages/bare-os-protocol/lib/channel.js
+3. Seeder and booter call sites
+4. Protocol tests and docs/reference/package-bare-os-protocol.md
+
+Run npm run test -w bare-os-protocol and capability contract verifiers after edits.
@@ -0,0 +1,10 @@
+---
+name: shell-grammar-change
+description: Shell tokenizer/parser — grammar-first, fixtures, shell roadmap docs.
+tags: [shell, grammar, posix]
+requires: [read_man_page, verification_hints]
+---
+
+# shell-grammar-change
+
+Read developer-guide/18-how-to-add-shell-grammar-feature.md. Update docs/reference/shell-grammar.md, shell-unsupported-behavior.md, shell-troubleshooting.md when semantics change. Run test:shell-fast and verify:shell-roadmap when applicable.