Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* SkillOpt bundled-skill mutation gate (D16).
*
* A "bundled" skill is one that lives in the gbrain repo's `skills/` tree
* (shipped alongside the binary). These are load-bearing for production
* workflows; mutating them via SkillOpt without explicit operator opt-in
* is too risky. By default, bundled-skill optimization runs in `--no-mutate`
* mode automatically — the proposed best is written to `proposed.md` for
* human review.
*
* User-owned skills (under a user's `~/.gbrain/skills/` or their own
* project's `skills/`) are NOT bundled — they can be mutated freely.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import { autoDetectSkillsDirReadOnly } from '../repo-root.ts';
import { errorFor } from '../errors.ts';
import { MIN_HELD_OUT_SIZE } from './held-out.ts';
import type { BundledSkillContext } from './types.ts';
/**
* Build the bundled-skill context for a (skillsDir, skillName) pair.
*
* The resolution chain:
* 1. Resolve the absolute skill path: `skillsDir/<name>/SKILL.md`.
* 2. Check whether the skillsDir came from the install-path fallback
* (i.e. it's `<gbrain-install>/skills`). If so, this is a bundled skill.
* 3. Otherwise, the skill is user-owned and freely mutable.
*/
export function getBundledSkillContext(skillsDir: string, skillName: string): BundledSkillContext {
const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
// Detect bundled by checking whether autoDetectSkillsDirReadOnly would
// have routed here via the install-path fallback. The simpler heuristic:
// if the resolved skillsDir is under the gbrain install tree (somewhere
// up the chain has node_modules/gbrain or VERSION matching this binary),
// it's bundled. Use the read-only detector to find the canonical install
// skillsDir and compare.
const detected = autoDetectSkillsDirReadOnly(process.cwd());
const isBundled = detected.source === 'install_path' && detected.dir !== null
&& resolvesToSame(detected.dir, skillsDir);
return { skillName, skillsDir, skillPath, isBundled };
}
function resolvesToSame(a: string, b: string): boolean {
try {
return fs.realpathSync(a) === fs.realpathSync(b);
} catch {
return path.resolve(a) === path.resolve(b);
}
}
/**
* Decide whether SkillOpt should mutate SKILL.md or just write proposed.md.
*
* Logic:
* - `--no-mutate` flag → never mutate (write proposed.md).
* - Bundled skill + no `--allow-mutate-bundled` → never mutate (D16).
* - User-owned skill (or bundled + `--allow-mutate-bundled`) → mutate
* in place.
*/
export function shouldMutateSkillFile(
ctx: BundledSkillContext,
flags: { noMutate: boolean; allowMutateBundled: boolean },
): { mutate: boolean; reason?: string } {
if (flags.noMutate) {
return { mutate: false, reason: 'user_passed_no_mutate' };
}
if (ctx.isBundled && !flags.allowMutateBundled) {
return { mutate: false, reason: 'bundled_skill_requires_allow_flag' };
}
return { mutate: true };
}
/**
* D16 ENFORCE (core mutation policy). Mutating a BUNDLED skill in place
* requires a NON-EMPTY held-out set (>= MIN_HELD_OUT_SIZE) — an empty/missing
* one passes the held-out gate vacuously and re-opens the benchmark-gaming
* hole. Throws (hard-refuse) when the requirement is unmet; no-op otherwise.
*
* Pure + side-effect-free (no fs, no engine) so every entry point that funnels
* through runSkillOpt — CLI, batch, fleet, cycle, background job, run_skillopt
* MCP op — inherits the check, and it's unit-testable without install-path
* detection (which is always false in a tempdir).
*/
export function assertBundledMutationHeldOut(input: {
isBundled: boolean;
willMutate: boolean;
heldOutCount: number;
skillName: string;
}): void {
if (input.willMutate && input.isBundled && input.heldOutCount < MIN_HELD_OUT_SIZE) {
throw errorFor({
class: 'HeldOutRequired',
code: 'held_out_required_for_bundled',
message: `Mutating bundled skill '${input.skillName}' in place requires a non-empty held-out set (>= ${MIN_HELD_OUT_SIZE} rows); got ${input.heldOutCount}.`,
hint: `add --held-out <path> (>= ${MIN_HELD_OUT_SIZE} rows), or drop --allow-mutate-bundled to get proposed.md for review.`,
});
}
}