Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: fold the skill resolver key-files page into the skills page so the key-files index stays under its size cap
garrytan329c0545ae1c
diff --git a/docs/architecture/KEY_FILES.md b/docs/architecture/KEY_FILES.mdindex e431ef64f8..f7714f548d 100644--- a/docs/architecture/KEY_FILES.md+++ b/docs/architecture/KEY_FILES.md@@ -75,7 +75,6 @@ link it here; never raise the cap.| [Runtime](key-files/runtime.md) | `src/core/abort-check.ts` through `src/core/zombie-reap.ts` || [Security](key-files/security.md) | `src/core/destructive-guard.ts` through `src/core/write-gate-scan.ts`; [purge](key-files/memory-purge.md) || [Shared brain skills](key-files/shared-skills.md) | Canonical catalog, enrollment, migration, publication and harness integration |-| [Skill resolver](key-files/skill-resolver.md) | `src/core/skills/resolver/`, `gbrain skills index/resolve/library`, the hook lane and the Node bundle || [Skills](key-files/skills.md) | `src/core/audit-skill-brain-first.ts` through `src/core/skills-integrity.ts` || [Tooling And Tests](key-files/tooling-and-tests.md) | `.github/workflows/test.yml` through `test/remote-privacy-sweep.test.ts` || [CI Health And Test Guards](key-files/ci-health-and-test-guards.md) | `nightly-watch.yml` through `check-image-decoders-embedded.sh`, contributor audit, fix-wave gate |diff --git a/docs/architecture/key-files/skill-resolver.md b/docs/architecture/key-files/skill-resolver.mddeleted file mode 100644index 9081a738a7..0000000000--- a/docs/architecture/key-files/skill-resolver.md+++ /dev/null@@ -1,32 +0,0 @@-# Key files — skill resolver--The engine-free skill resolver behind `gbrain skills index` and-`gbrain skills resolve`. Guide: [docs/guides/skill-resolver.md](../../guides/skill-resolver.md).-Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under-`src/core/skills/resolver/` is a leaf: no engine, operations table, provider or-`skill-catalog.ts` import, static or dynamic (`test/skill-resolver-module-graph.test.ts`).--- `src/core/skills/resolver/index.ts` — the library entry (`gbrain/skill-resolver` export, and the entry of the Node bundle `gbrain-skill-resolver.mjs`). Re-exports build, status, remove, resolve, `ResolverError`, `resolverHome`; `resetSkillSession` deletes one session's state.-- `src/core/skills/resolver/resolve.ts` — one turn: `normalizeTurnInput` (the turn-input schema, unknown fields refused, message capped at 8 KB), catalog loading (receipt and ranker identity, index size, gbrain version, the sliced stat freshness check: at most `STAT_CHECK_SLICE` entries per turn, a full sweep at most once per `STAT_CHECK_INTERVAL_MS`, cursor in `stat-check`), ack and no_match, explicit mentions first, merged-catalog interleave, the session rules (k 5/3/1 at 50%/80% of the budget, strong-match pacing, no-repeat, one re-suggestion after 10 turns), the block, `explain`, `failOpen`, `deadlineMs`. Returns `commit()`; session state changes only through it. Pinned by `test/skill-resolver.test.ts` and `test/skill-resolver-contract.test.ts`.-- `src/core/skills/resolver/rank.ts` — the A5 BM25F ranker over an `IndexReader` (scores summed in the prototype's order, ranked by score over summed idf, ties by name then id), the multilingual acknowledgement list, `mentionsSkill` (a `/name` counts only as a leading slash command) and `reasonText`. `test/skill-resolver-reproduction.test.ts` pins top-5 equality with the Step 1 prototype.-- `src/core/skills/resolver/tokenize.ts` — `splitWords` (shared with `scoreSkillMatch` in `skill-catalog.ts`) and `lexTerms`, the frozen Step 1 term rule (stopwords, light stemming); CJK runs become overlapping bigrams. Vectors: `test/fixtures/skill-resolver/tokenizer-vectors.json`.-- `src/core/skills/resolver/index-format.ts` — `index.bin` (magic `GBSKIDX1`, JSON header, field-length averages, per-skill lengths, sorted term dictionary, flat postings with per-field tf, per-skill meta), byte-identical for identical records; `VARIANT_PARAMS` (D and T constants), `fieldText`, `summaryOf` (the description cut at 120 characters), `IndexReader` (lazy postings and meta reads).-- `src/core/skills/resolver/build.ts` — `buildSkillIndex` under the catalog lease (variant choice: T at a 25% trigger-or-routing share, kept down to 20%; publication only while the lease is held and the directory exists, receipt written last), `catalogStatus` (content tier: re-reads the source and re-hashes the index), `removeSkillIndex` (rename then delete, so a concurrent build fails `skill_index_removed`), `listCatalogs`, `sessionStatus`, `dirFingerprintSlice`, `catalogHash`.-- `src/core/skills/resolver/sources.ts` — the three sources: `--dir` (real paths only, symlinks out of the root skipped, breadth-first, first id wins, plugin namespace from `.claude-plugin/plugin.json`, stat fingerprint), `--bundled` (dynamic import of `src/core/skills/bundled.ts`, never the operations table) and `--from-json` (8 MB, 10,000 entries); `applyRouting`; bounds (`MAX_SKILLS`, `MAX_DIRS_VISITED`, `MAX_DEPTH`).-- `src/core/skills/resolver/frontmatter.ts` — bounded SKILL.md reader (64 KB file, 4 KB body): name, description, `when_to_use`, triggers, `disable-model-invocation`.-- `src/core/skills/resolver/routing.ts` — one RESOLVER-style routing file's table and compact-list rows, skipping the generated skills block.-- `src/core/skills/resolver/session.ts` — session state (`sessions/<sha256(scope, harness, id)>.json`: ids and counters only), `commitSession` under a short lease, file and id caps, 7-day GC with a per-run work bound.-- `src/core/skills/resolver/block.ts` — the `<relevant_skills>` block: header, one JSON-quoted line per suggestion (id, name, path for codex and openclaw, summary unless names-only), one load line per harness or `--load-hint`, cut at whole lines to 400 tokens by `estimateTokens`.-- `src/core/skills/resolver/lock.ts` — ownership leases (O_EXCL create, random token, expiry; reclaimed only after expiry; release and renewal check the token).-- `src/core/skills/resolver/config.ts` — `skills.resolver.session_token_budget` (0 or 100-50,000, default 2,000) and `auto_rebuild` / `GBRAIN_SKILLS_NO_AUTOREBUILD=1`, read straight from `config.json`.-- `src/core/skills/resolver/paths.ts` — `resolverHome` (GBRAIN_HOME convention), catalog-name rule and confinement under `skill-index/`, the fixed file names.-- `src/core/skills/resolver/errors.ts` — `ResolverError` codes (rows in `src/core/error-registry.ts`), `USAGE_CODES` (exit 2).-- `src/core/skills/resolver/fsutil.ts` — temp-file, fsync and rename writes; bounded reads.-- `src/core/skill-description.ts` — `oneLineDescription` (frontmatter description, block scalars folded, else the first body paragraph), shared by `skill-catalog.ts`, `bundled.ts` and the bundled source.-- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check): async config/stdin/carrier reads on the main thread, ranking in a worker (source: `hook-worker.ts` beside it; compiled binary: the second build entrypoint at `WORKER_SRC_PATH`, so every `bun build --compile` that ships a binary lists it), a 50 ms deadline that exits the process with no output and no commit, the commit (`commitSessionAsync`) on the main thread after delivery, the payload budget (`skills.resolver.lane_payload_chars`, dropped whole as `payload_dropped`), the one-owner rule (first carrier entry whose home has the lane on), the SessionStart compaction reset, the Claude Code project catalog (`claude-code-project-<root hash>`, built by a detached `skills index build`, stamp-limited to once a minute) and `skill-index/logs/lane.jsonl`. Test seams: `GBRAIN_TEST_SKILL_LANE_STALL`, `GBRAIN_TEST_SKILL_LANE_DEADLINE_MS`. Pinned by `test/skill-resolver-hook-lane.test.ts`.-- `src/core/setup/skill-resolver-{lane,hook,config,setup}.ts` — `setup <claude-code|codex> --skill-loading resolve|off` and `--remove`: the lane identity leaf (marker `skill-resolver-v1`, which every other lane's ownership and yield test excludes), the Claude Code entries and the Codex group plus its `config.toml` trust, the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.-- `src/commands/doctor/checks/skill-resolver.ts` — doctor `skill_resolver` (emitted by the `harness_wiring` entry, whose details carry the same view): hook state, each catalog's content-tier freshness, recent lane outcomes and error codes; silent when nothing of the resolver exists.-- `src/commands/skill-resolver.ts` — the CLI (`src/cli/commands/skill-resolver.ts` dispatches; `src/cli/command-route.ts` routes only `skills index`, `skills resolve` and `skills library` here, so plain `gbrain skills` stays `list_skills`). Exit 0, 1 (runtime error), 0 with `--fail-open`, 2 (usage); commits a session turn only after stdout is written. Pinned by `test/skill-resolver-cli.test.ts` and `test/skill-resolver-guide.test.ts`.-- `scripts/bench-skill-resolver.ts` — the latency bars (cold turn p95: 10 ms at 1,000 skills, 40 ms at 7,500), enforced by `.github/workflows/skill-resolver-bench.yml` on a 2-vCPU runner.-- `src/commands/skill-resolver-library.ts` — the one Node-bundle builder (Bun.build of the library entry, written atomically, sha256 returned) behind `gbrain skills library` (default `GBRAIN_HOME/.gbrain/lib/gbrain-skill-resolver.mjs`) and the release script; a compiled binary has no source and refuses with `skill_source_unreadable`. Pinned by `test/skill-resolver-packaging.test.ts`.-- `scripts/build-skill-resolver-bundle.ts` — builds and Node-smoke-tests `gbrain-skill-resolver.mjs` and writes its `.sha256`; the release job `skill-resolver-bundle` attaches both and checks the sum before publishing.diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.mdindex 49811df8e5..871a85288b 100644--- a/docs/architecture/key-files/skills.md+++ b/docs/architecture/key-files/skills.md@@ -2,7 +2,6 @@[Subsystem index](../KEY_FILES.md). Read only the entries relevant to your change.Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.-The engine-free skill resolver (`src/core/skills/resolver/`, `gbrain skills index|resolve`) has its own page: [skill-resolver.md](skill-resolver.md).- `skills/conventions/agent-operator-protocol.md` — GENERATED copy of `docs/protocol/AGENT_OPERATOR_v1.md` (`bun run build:agent-protocol`; never hand-edit). It ships inside the skills tree so skill links to the protocol resolve in every copy (skillpack scaffold, harness skill dirs, plugin trees); skills link it relatively and every other repo doc by absolute URL (`scripts/portable-skill-links.ts`).@@ -37,3 +36,36 @@ The engine-free skill resolver (`src/core/skills/resolver/`, `gbrain skills inde- `src/core/skillpack/{personas,bridge-state,harness-bridge}.ts` + `src/commands/skillpack/{shared,scaffold,reference,harness}.ts` — the harness skill bridge. `src/commands/skillpack.ts` is a peeled FAÇADE (dispatch + HELP_TOP + the install/uninstall removal errors; module-size ratchet); per-subcommand handlers live in `src/commands/skillpack/` and the flag registry scans the dir via the façade's `facadeExpansion` entry — spell foreign CLI flags dash-less in these modules' comments/strings (prose-bleed class). `scaffold --harness <claude-code|openclaw|codex|opencode>` installs a persona-curated set into the harness's native skills dir: personas live in `skills/plugin-lanes.json#personas` (`personas.ts` is the SINGLE validation implementation — `scripts/generate-plugin-tree.ts` imports it; membership ⊆ the plugin lane set, so lane-excluded slugs are refused with their recorded reason); slugs path-resolve via `bundle.ts`'s `universe:'manifest'` (the 8 lane additions are all absent from openclaw.plugin.json#skills). Safety: frontmatter fail-loud gate pre-write (a frontmatterless SKILL.md bricks Codex sessions), target-side confinement in `assertTargetsConfined` (deepest-existing-ancestor realpath — copy.ts confines SOURCES only), refuse-overwrite, and written-only ownership in `bridge-state.ts` (`~/.gbrain/skillpack-bridge-state.json`, schema `gbrain-skillpack-bridge-v1`, fail-open load, install-time sha256 per written file — never touches `skillpack-state.json`, whose loader drops unknown keys). `--stub` renders cold-pull pointers (frontmatter verbatim + `<!-- gbrain-skill-stub v1 -->` marker; ships the shared-dep closure AND sibling aux files — `get_skill` serves only the SKILL.md body) behind a three-check preflight in `src/commands/skillpack/harness.ts` (publish gate dual-plane, per-slug servability via `verifySlugsServable`, best-effort local surface warn — the module deliberately does NOT import `src/mcp/surface.ts`, whose comments would bleed serve flags into the allowlist; `get_skill ∉ STARTER_OPS` is pinned by a contract test). `reference --harness` is a stub-aware three-way lens (`local_edit` vs `upstream_drift` vs `unknown` — no install-time hash, never auto-applied — via the hash ledger; marker fallback survives state loss both directions) + `--apply-clean-hunks` (refuses stub files); `remove --harness` deletes ledger-owned files only; `skillpack status` renders an installed-bridges section from `collectBridgesStatus`. openclaw delegates to `runScaffold({skillSlugs})`; codex/opencode require an explicit dest until observation runs. Claude-code dirs come from `host-specs.ts` (`claudeUserSkillsDir`/`claudeProjectSkillsDir`, HOME-env-first). Tests: `test/skillpack-{personas,bridge-state,harness-bridge,reference-harness,scaffold-harness}.test.ts`. Doc: the harness-bridge section of `docs/guides/skillpacks-as-scaffolding.md`. #5912: `ownedBridgeSlugs(entry)` (harness-bridge.ts) is the one accessor for an install's skill slugs without the reserved `SHARED_DEP_LEDGER_KEY`, used by the no-slug reference lens, bridge status and remove; the scaffold "Update lens" / remove hints repeat the `--dest`, `--scope project` and `--workspace` the user passed.- `src/core/skills-integrity.ts` — Tamper-evidence manifest for the bundled `skills/` tree; NOT a signature system. Pure functions over `node:crypto` sha256: `computeSkillsManifest(dir)` (recursive, sorted '/'-relative paths, excludes the manifest itself, skips symlinks), `renderSkillsManifest(dir)` (2-space JSON + trailing newline, deterministic), `verifySkillsManifest(dir, manifest)` → `{modified, missing, extra}`. Committed manifest lives at `skills/skills.lock.json` (`SKILLS_MANIFEST_FILENAME`); regenerate via `bun run scripts/generate-skills-manifest.ts`. Consumers: the warn-only `skills_manifest_integrity` doctor check in `src/commands/doctor/skill-checks.ts` (ok/skip when no manifest is present — user workspaces and compiled-binary installs are not drift) and the CI freshness guard `scripts/check-skills-manifest-fresh.sh` (`bun run check:skills-manifest`, in `bun run verify`). Pinned by `test/skills-integrity.test.ts`.++## Skill resolver++The engine-free skill resolver behind `gbrain skills index` and+`gbrain skills resolve`. Guide: [docs/guides/skill-resolver.md](../../guides/skill-resolver.md).+Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under+`src/core/skills/resolver/` is a leaf: no engine, operations table, provider or+`skill-catalog.ts` import, static or dynamic (`test/skill-resolver-module-graph.test.ts`).++- `src/core/skills/resolver/index.ts` — the library entry (`gbrain/skill-resolver` export, and the entry of the Node bundle `gbrain-skill-resolver.mjs`). Re-exports build, status, remove, resolve, `ResolverError`, `resolverHome`; `resetSkillSession` deletes one session's state.+- `src/core/skills/resolver/resolve.ts` — one turn: `normalizeTurnInput` (the turn-input schema, unknown fields refused, message capped at 8 KB), catalog loading (receipt and ranker identity, index size, gbrain version, the sliced stat freshness check: at most `STAT_CHECK_SLICE` entries per turn, a full sweep at most once per `STAT_CHECK_INTERVAL_MS`, cursor in `stat-check`), ack and no_match, explicit mentions first, merged-catalog interleave, the session rules (k 5/3/1 at 50%/80% of the budget, strong-match pacing, no-repeat, one re-suggestion after 10 turns), the block, `explain`, `failOpen`, `deadlineMs`. Returns `commit()`; session state changes only through it. Pinned by `test/skill-resolver.test.ts` and `test/skill-resolver-contract.test.ts`.+- `src/core/skills/resolver/rank.ts` — the A5 BM25F ranker over an `IndexReader` (scores summed in the prototype's order, ranked by score over summed idf, ties by name then id), the multilingual acknowledgement list, `mentionsSkill` (a `/name` counts only as a leading slash command) and `reasonText`. `test/skill-resolver-reproduction.test.ts` pins top-5 equality with the Step 1 prototype.+- `src/core/skills/resolver/tokenize.ts` — `splitWords` (shared with `scoreSkillMatch` in `skill-catalog.ts`) and `lexTerms`, the frozen Step 1 term rule (stopwords, light stemming); CJK runs become overlapping bigrams. Vectors: `test/fixtures/skill-resolver/tokenizer-vectors.json`.+- `src/core/skills/resolver/index-format.ts` — `index.bin` (magic `GBSKIDX1`, JSON header, field-length averages, per-skill lengths, sorted term dictionary, flat postings with per-field tf, per-skill meta), byte-identical for identical records; `VARIANT_PARAMS` (D and T constants), `fieldText`, `summaryOf` (the description cut at 120 characters), `IndexReader` (lazy postings and meta reads).+- `src/core/skills/resolver/build.ts` — `buildSkillIndex` under the catalog lease (variant choice: T at a 25% trigger-or-routing share, kept down to 20%; publication only while the lease is held and the directory exists, receipt written last), `catalogStatus` (content tier: re-reads the source and re-hashes the index), `removeSkillIndex` (rename then delete, so a concurrent build fails `skill_index_removed`), `listCatalogs`, `sessionStatus`, `dirFingerprintSlice`, `catalogHash`.+- `src/core/skills/resolver/sources.ts` — the three sources: `--dir` (real paths only, symlinks out of the root skipped, breadth-first, first id wins, plugin namespace from `.claude-plugin/plugin.json`, stat fingerprint), `--bundled` (dynamic import of `src/core/skills/bundled.ts`, never the operations table) and `--from-json` (8 MB, 10,000 entries); `applyRouting`; bounds (`MAX_SKILLS`, `MAX_DIRS_VISITED`, `MAX_DEPTH`).+- `src/core/skills/resolver/frontmatter.ts` — bounded SKILL.md reader (64 KB file, 4 KB body): name, description, `when_to_use`, triggers, `disable-model-invocation`.+- `src/core/skills/resolver/routing.ts` — one RESOLVER-style routing file's table and compact-list rows, skipping the generated skills block.+- `src/core/skills/resolver/session.ts` — session state (`sessions/<sha256(scope, harness, id)>.json`: ids and counters only), `commitSession` under a short lease, file and id caps, 7-day GC with a per-run work bound.+- `src/core/skills/resolver/block.ts` — the `<relevant_skills>` block: header, one JSON-quoted line per suggestion (id, name, path for codex and openclaw, summary unless names-only), one load line per harness or `--load-hint`, cut at whole lines to 400 tokens by `estimateTokens`.+- `src/core/skills/resolver/lock.ts` — ownership leases (O_EXCL create, random token, expiry; reclaimed only after expiry; release and renewal check the token).+- `src/core/skills/resolver/config.ts` — `skills.resolver.session_token_budget` (0 or 100-50,000, default 2,000) and `auto_rebuild` / `GBRAIN_SKILLS_NO_AUTOREBUILD=1`, read straight from `config.json`.+- `src/core/skills/resolver/paths.ts` — `resolverHome` (GBRAIN_HOME convention), catalog-name rule and confinement under `skill-index/`, the fixed file names.+- `src/core/skills/resolver/errors.ts` — `ResolverError` codes (rows in `src/core/error-registry.ts`), `USAGE_CODES` (exit 2).+- `src/core/skills/resolver/fsutil.ts` — temp-file, fsync and rename writes; bounded reads.+- `src/core/skill-description.ts` — `oneLineDescription` (frontmatter description, block scalars folded, else the first body paragraph), shared by `skill-catalog.ts`, `bundled.ts` and the bundled source.+- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check): async config/stdin/carrier reads on the main thread, ranking in a worker (source: `hook-worker.ts` beside it; compiled binary: the second build entrypoint at `WORKER_SRC_PATH`, so every `bun build --compile` that ships a binary lists it), a 50 ms deadline that exits the process with no output and no commit, the commit (`commitSessionAsync`) on the main thread after delivery, the payload budget (`skills.resolver.lane_payload_chars`, dropped whole as `payload_dropped`), the one-owner rule (first carrier entry whose home has the lane on), the SessionStart compaction reset, the Claude Code project catalog (`claude-code-project-<root hash>`, built by a detached `skills index build`, stamp-limited to once a minute) and `skill-index/logs/lane.jsonl`. Test seams: `GBRAIN_TEST_SKILL_LANE_STALL`, `GBRAIN_TEST_SKILL_LANE_DEADLINE_MS`. Pinned by `test/skill-resolver-hook-lane.test.ts`.+- `src/core/setup/skill-resolver-{lane,hook,config,setup}.ts` — `setup <claude-code|codex> --skill-loading resolve|off` and `--remove`: the lane identity leaf (marker `skill-resolver-v1`, which every other lane's ownership and yield test excludes), the Claude Code entries and the Codex group plus its `config.toml` trust, the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.+- `src/commands/doctor/checks/skill-resolver.ts` — doctor `skill_resolver` (emitted by the `harness_wiring` entry, whose details carry the same view): hook state, each catalog's content-tier freshness, recent lane outcomes and error codes; silent when nothing of the resolver exists.+- `src/commands/skill-resolver.ts` — the CLI (`src/cli/commands/skill-resolver.ts` dispatches; `src/cli/command-route.ts` routes only `skills index`, `skills resolve` and `skills library` here, so plain `gbrain skills` stays `list_skills`). Exit 0, 1 (runtime error), 0 with `--fail-open`, 2 (usage); commits a session turn only after stdout is written. Pinned by `test/skill-resolver-cli.test.ts` and `test/skill-resolver-guide.test.ts`.+- `scripts/bench-skill-resolver.ts` — the latency bars (cold turn p95: 10 ms at 1,000 skills, 40 ms at 7,500), enforced by `.github/workflows/skill-resolver-bench.yml` on a 2-vCPU runner.+- `src/commands/skill-resolver-library.ts` — the one Node-bundle builder (Bun.build of the library entry, written atomically, sha256 returned) behind `gbrain skills library` (default `GBRAIN_HOME/.gbrain/lib/gbrain-skill-resolver.mjs`) and the release script; a compiled binary has no source and refuses with `skill_source_unreadable`. Pinned by `test/skill-resolver-packaging.test.ts`.+- `scripts/build-skill-resolver-bundle.ts` — builds and Node-smoke-tests `gbrain-skill-resolver.mjs` and writes its `.sha256`; the release job `skill-resolver-bundle` attaches both and checks the sum before publishing.