Garry's Opinionated OpenClaw/Hermes Agent Brain
CI guards
The guard registry, its self-test and the source guards it runs. Moved out of TESTING.md to keep that file under its size cap.
Guard registry and self-test
The privacy and test-isolation guards use scripts/lib/guard-candidates.sh to
scan fresh file contents in bounded batches before applying their detailed
per-file rules. They do not cache passing results. Candidate scanner failures
fail the guard, and matching files retain the same allowlists and diagnostics.
scripts/guards-manifest.tsv is THE single registry of scripts/check-*
guards, each classified scanner (greps/parses repo sources —
must eventually carry fixtures), buildfresh, or repostate (build/freshness
guards are exempt-with-reason, not fixture-tested).
scripts/guard-self-test.sh (bun run check:guard-self-test, wired into
bun run verify) proves every selftest=yes scanner CAN fail: it runs each
one against known-bad (must exit non-zero) and known-good (must pass) fixture
trees under test/fixtures/guards/<guard>/{bad,good}/ via the
GBRAIN_GUARD_ROOT env seam (guards run 4 at a time, GUARD_SELF_TEST_JOBS
overrides; results print in manifest order; the whole pass must finish inside
its 30 s budget), and enforces manifest completeness — a new
scripts/check-* script that isn't registered in the manifest fails the
build. A guard whose pattern rots into a permanently-green no-op fails CI
instead of masquerading as coverage.
A guard may carry extra known-bad trees named bad-<variant>/; each one must
fail on its own. Refactor wave 1 adds one inside each split module location for
every scanner that names a split file, listed in
docs/designs/refactor-wave-1/path-consumers.md.
Layering guard
scripts/check-layering.ts (bun run check:layering, in bun run verify)
parses every file under src/core/engine-sql/, src/core/schema-migrations/
and src/core/persistence/ and fails on any import, type-only included, of an
engine façade (pglite-engine.ts, postgres-engine.ts, engine-factory.ts)
from engine-sql, of src/core/migrate.ts from schema-migrations, or of
src/core/ai/gateway.ts from persistence. The first two directories are loaded
by the engines and by migrate.ts, so an import back up is an ESM cycle that
can fail with a temporal-dead-zone error at module load. Take the executor as a
parameter and import types from src/core/engine.ts; migration helpers live in
schema-migrations/helpers.ts and the Migration type in
schema-migrations/types.ts; persistence embeds via src/core/embedding.ts.
Write-path model guards
scripts/check-ai-sdk-importers.ts (in bun run verify) fails when a file
outside scripts/ai-sdk-importers.allowlist imports a provider SDK (ai,
@ai-sdk/*, @anthropic-ai/sdk, openai) as a value, so every model call
goes through invokeAI. Each mutating op has a write-inference class
(src/core/ops/write-inference.ts). test/write-path-zero-llm.serial.test.ts
asserts no generative call before commit and only attributed facts extraction
after it; test/write-path-no-egress.serial.test.ts: keyless CLI writes open
no connection. Helper: test/helpers/ai-tripwire.ts.
Durable-flush guard
scripts/check-durable-flush.ts (bun run check:durable-flush, in
bun run verify) fails on an fsyncSync(fd) anywhere in src/ outside
src/core/fs-durable.ts whose fd is assigned from a read-only openSync
(flags omitted, a flag string without w/a/+, or O_RDONLY without
O_WRONLY/O_RDWR), file or directory, and on one whose flags it cannot
read: Windows refuses fsync on a read-only handle and has no directory flush
(EPERM; #5595, #5475). Fix: fsync the descriptor you wrote through before
closing it (fchmodSync(fd) first for its final mode), or call flushFile /
flushDirectory(path, { bestEffort? }) from src/core/fs-durable.ts. A file
that cannot migrate yet goes in the guard's ALLOWLIST with a reason; a stale
entry fails. Fixtures: test/fixtures/guards/check-durable-flush.ts/. The
#5595/#5475 regressions run natively on the windows-latest row of the
test.yml security-regressions job; test/helpers/win32-flush-semantics.ts
makes them discriminate on POSIX.
Windows hidden-console guard
scripts/check-windows-hide.ts (bun run check:windows-hide, in verify;
#4992): a runtime child_process import or Bun.spawn* in src/ outside
src/core/spawn.ts fails unless the file is in NOT_YET_MIGRATED (a ratchet;
a stale entry fails); windowsHide: false needs an ALLOWLIST reason.
test/windows-hidden-console.test.ts is the native proof on the same row.
Engine-sql ratchet
scripts/check-engine-sql-ratchet.ts (bun run check:engine-sql-ratchet, in
bun run verify) keeps each storage domain's SQL in one place,
src/core/engine-sql/<domain>.ts, by stopping SQL from growing back into the
engines. It parses src/core/pglite-engine.ts, src/core/postgres-engine.ts
and every file under src/core/pglite-engine/ and src/core/postgres-engine/,
and names each class member (PostgresEngine.getPage), top-level function and
top-level variable (insertFact). A unit is SQL-bearing when the literal text
of a string, template, tagged template or + chain inside it has SQL
structure: SELECT ... FROM <x>, SELECT <fn>(, INSERT INTO <x>,
UPDATE <x> [alias] SET, DELETE FROM <x>, WITH <x> AS (,
CREATE|ALTER|DROP <object kind>, TRUNCATE <x>, SET LOCAL <x>,
ON CONFLICT, WHERE ... ORDER BY|GROUP BY|LIMIT, or a $<n>::type cast.
Comments and identifiers never count. Keywords match in upper or lower case
but never Title Case, and a lowercase match also needs a second SQL signal
(where, returning, $1, ::, ;, * and similar), so "Select a file"
or "could not delete from cache" is not SQL.
scripts/engine-sql-baseline.tsv lists migrated<TAB><domain> rows (the
domain's module must exist under src/core/engine-sql/) and
method<TAB><path><TAB><QualifiedName> rows for the SQL-bearing members that
remain. Rows only shrink. The guard fails on:
- a new SQL-bearing member with no row: move the SQL into
src/core/engine-sql/<domain>.tsand delegate, or mark the declaration (on its line or the line above) with// engine-sql-ok: <reason>; an empty reason fails; - a stale row, whose member is gone, no longer SQL-bearing or now marked:
delete it, or run
bun scripts/check-engine-sql-ratchet.ts --prune, which drops stale and duplicate rows and never adds one; - a duplicate or malformed row, or a
migratedrow with no module.
When a domain moves, delete its members' rows and add its migrated row in
the same commit.
Engine raw-SQL ratchet
scripts/check-engine-raw-sql-ratchet.ts (bun run check:engine-raw-sql-ratchet,
in bun run verify) keeps raw SQL outside the engines from growing while it
moves behind typed engine methods (D6 in docs/designs/RUST_ENGINE.md, "Track 2
rules"). It parses every .ts file under src/ except the engines
(src/core/engine.ts, src/core/pglite-engine.ts, src/core/postgres-engine.ts,
src/core/pglite-engine/, src/core/postgres-engine/ and
src/core/engine-sql/) and counts, per file:
execute_raw: calls namedexecuteRaw,executeRawDirectorexecuteRawJsonb, whatever the receiver (the engine, a transaction, a helper that takesPick<BrainEngine, 'executeRaw'>, an executor), with a dot or a literal bracket (e['executeRaw'](...));sql_template: tagged templates whose literal text has SQL structure;driver_call:.unsafe(...), and.query(...)or.exec(...)with an argument whose literal text has SQL structure.
SQL structure is the engine-sql ratchet's test, so comments and prose never
count. A SQL string held in a variable and passed to .query(v) is not seen.
scripts/engine-raw-sql-baseline.tsv holds path<TAB>metric<TAB>count rows,
with an optional fourth note column, generated from the tree (--print). A
higher count or a file with no row fails, and so does a lower count until its
row is lowered (bun scripts/check-engine-raw-sql-ratchet.ts --prune lowers
stale rows, keeps their notes and never raises one). Instead of a new site,
call a typed engine method, or add one with its SQL in
src/core/engine-sql/<domain>.ts (CONTRIBUTING.md "Storage method"). When a
fix must add a site before its area is converted, raise the row (or add it) in
the same PR and write the reason in the note column, as
scripts/module-size-limits.tsv does; a reviewer sees the baseline change. A
moved or split file carries its rows with it in the same PR.
Engine-kind branches
scripts/check-engine-kind-branches.ts (bun run check:engine-kind-branches,
in bun run verify) counts two-way engine branches per file over the same
files: kind_compare (x === 'pglite', x !== 'postgres', either side,
where x ends in kind, engineKind, engine_kind or engine) and
kind_case (case 'pglite': in a switch over such x). A third engine must
not fall silently into one of these branches, so new code asks a capability
question or switches over every engine kind with a default clause whose
first statement hands the switched value to a never check
(const unreachable: never = kind;, kind satisfies never;,
assertNever(kind);, or return / throw assertNever(kind);). Such an
exhaustive switch never counts: a third engine fails typecheck there instead.
A check after other statements, inside a nested function, on a shadowing name
or through a cast (kind as never) does not exempt a switch. Baseline
scripts/engine-kind-branches-baseline.tsv, same rules as above.
Page body readers
bun run check:page-body-readers (in verify): every site that reads or writes
a page body as one string has a row in scripts/page-body-readers-baseline.tsv
naming what it must become; rows only shrink. Rules: the script's header.
Engine-sql dynamic SQL
scripts/check-engine-sql-dynamic.ts (bun run check:engine-sql-dynamic, in
bun run verify) parses every file under src/core/engine-sql/ except
fragment.ts, the renderer, which writes $n and splices trusted text by
design. In engine-sql every value reaches SQL as a bound parameter through
sqlFragment, and only constant text is spliced. Trusted text is a string
literal; a const in the same file initialized with trusted text or an
as const object or array literal (members and element accesses included); a
CONSTANT_ALLOWLIST name (ENRICH_ORDER_SQL); a call to a VETTED_BUILDERS
entry (pageReadFilter, buildRecencyComponentSql,
privatePagesFilterFragment, currentCodeEdgeFilter, buildCJKKeywordSql,
currentTextProjectionFilter); a template or + chain whose parts are all
trusted or are numbers the same function checked earlier with
Number.isFinite(<same expression>); or a conditional whose branches are both
trusted. Both registries live in the script with a one-line reason each. The
guard fails on:
trustedSql(arg)with an arg that is not trusted text: bind the value with${value}insqlFragmentinstead, or register a new builder with its reason after review;- an untagged template or
+concatenation, passed directly or through a local variable (letappends included) as the SQL of.query(,.unsafe(,.executeRaw(orexecuteRawJsonb(, with an untrusted part: compose withsqlFragmentand run it withexecutor.run(fragment); - a literal
$<digit>, or a$right before a substitution, in a composed string (a template with substitutions, anysqlFragmenttemplate, any+operand): letrenderFragmentnumber the parameters. A static string passed as-is may carry$1; - an expanded list,
IN (right before a substitution or a non-literal+operand: bind the array as one parameter,= ANY(${ids}::text[]), so prepared-statement caches stay bounded.
Fixtures: test/fixtures/guards/check-engine-sql-dynamic.ts/; forms are
driven in test/scripts/engine-sql-dynamic.test.ts.
Engine-sql brands
scripts/check-engine-sql-brands.ts (bun run check:engine-sql-brands, in
bun run verify) keeps the RLS read brands in
src/core/engine-sql/brands.ts unforgeable. ScopedRead records a read that
ran inside withScopedReadTransaction on master and LegacyUnscopedRead one
that ran unscoped on the pool (EO4), so a forged brand silently changes how a
read is scoped. The guard fails on:
- a brand key (any
__obtainVia...name) in a text file undersrc/,test/orscripts/other thanbrands.tsand the guard's own script, fixtures and test: get a branded executor fromscopedRead(tx)insidewithScopedReadTransaction, or fromunscopedExecutor(executor, '<reason>'); - in
src/, a cast ontoScopedReadorLegacyUnscopedReadoutsidebrands.ts, anas unknown as TwhereTnamesSqlExecutor,ScopedReadorLegacyUnscopedRead, or a double cast passed straight toscopedRead(orunscopedExecutor(. Driver-handle casts such astx as unknown as PgConnindialect-postgres.tspass; - an import of
unscopedExecutororLegacyUnscopedRead(value, type, alias, re-export orimport('...').Xtype) from outside engine-sql, the two engine façades, doctor (src/commands/doctor.ts,src/commands/doctor/**,src/core/doctor*), maintenance (src/core/maintenance/**), admin (src/commands/admin*.ts,src/core/admin/**), migrations (src/core/migrate.ts,src/core/schema-migrations/**,src/commands/migrations/**) andtest/; an import ofscopedReadfrom outside engine-sql, the façades andtest/; or a namespace, dynamic orrequireimport ofbrands.tsfrom outside thatscopedReadlist.src/core/ops/**, the MCP-facing surface, is always denied. Take the branded executor from the engine façade instead.
The allowlists live in the script.
Retired-phrase guard
scripts/check-retired-phrases.sh (bun run check:retired-phrases, in
bun run verify, under a second) keeps the instructions agents follow
literally in step with refactor wave 1. It greps CLAUDE.md, AGENTS.md,
CONTRIBUTING.md, docs/ and skills/ for the contributor-workflow phrases
the wave retired: the old migrations-array wording and appending to it, the
rule that every engine method is written twice, the CLI switch-case step, the
migrate.ts region policy, and schema text listed as a hand-synced pair of
schema.sql and the PGLite schema module. The patterns and the current
instruction for each live in the script's RETIRED table. Historical records
may quote them and are exempt: docs/designs/, docs/test-audit/,
docs/incidents/, docs/plans/, docs/proposals/, docs/research/,
docs/issues/, docs/superpowers/, docs/migrations/, skills/migrations/
and the wave 1 porting kit (docs/architecture/wave-1-*); CHANGELOG.md is
not scanned. Each hit prints FAIL: <file:line> retired phrase "<match>",
then Why:, Fix: with the current instruction, and See:. The fix is to
rewrite the sentence to the current workflow, never to exempt the file. To
retire another phrase, add a row to RETIRED. Fixtures:
test/fixtures/guards/check-retired-phrases.sh/ (one bad-<location> tree per
scanned location); every pattern and the exemptions are driven in
test/scripts/check-retired-phrases.test.ts.
Bash 3.2 parse guard
macOS ships GNU bash 3.2.57 as /bin/bash, and its parser rejects shapes
bash 5 accepts. The one that broke every Mac (#5810) is a heredoc inside
$(...) whose body holds an odd quote. scripts/check-bash32.sh
(bun run check:bash32) runs the real 3.2 parser, bash -n, over every
tracked *.sh except the guard fixtures under test/fixtures/guards/. It
uses the first parser available: GBRAIN_BASH32=<path> (a bash 3.x binary),
/bin/bash when it is bash 3.x (stock macOS), or the digest-pinned bash:3.2
Docker image (GBRAIN_BASH32=docker forces the image). With none it prints
one skip line and exits 0; GBRAIN_TEST_BASH32_REQUIRE=1 makes that exit 2. Each
failure prints FAIL: <file:line>, Why: (macOS /bin/bash is 3.2), Fix:
(read heredoc text with IFS= read -r -d '' VAR <<'EOF' || true) and See:.
To reproduce one file by hand:
docker run --rm -v "$PWD":/w -w /w bash:3.2 bash -n <file>.
The guard checks parsing only. It is not in bun run verify, which must not
need Docker. The test.yml verify job runs it with GBRAIN_TEST_BASH32_REQUIRE=1
together with test/scripts/check-bash32.test.ts, whose real-parser cases
feed it the test/fixtures/guards/check-bash32.sh/{bad,good} trees. The
macOS 26 job runs it under /bin/bash and then runs bun run verify there,
which covers bash-4 runtime features the parser cannot see.