Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Post-write validator hook — runs after put_page / importFromContent
* succeeds, in LINT MODE only. Findings are logged; they do not reject
* the write.
*
* This is the PR 2.5 minimal integration: we want observability on how
* many pages the brain would reject in strict mode BEFORE flipping the
* strict-mode default (CEO plan: "follow-on release gated on BrainBench
* regression ≤1pt + 7-day soak + zero false-positive count").
*
* Gated on config `writer.lint_on_put_page`. Default: false (no change to
* current put_page behavior). When enabled, findings land in:
* - ingest_log (via engine.logIngest) — durable, agent-inspectable
* - ~/.gbrain/validator-lint.jsonl — local file for drift-over-time analysis
*
* Pages with `validate: false` frontmatter skip the validators entirely
* (grandfather opt-out from PR 2 migration).
*/
import { appendFileSync, existsSync, mkdirSync } from 'fs';
import { dirname } from 'path';
import { gbrainPath } from '../config.ts';
import type { BrainEngine } from '../engine.ts';
import { BUILTIN_VALIDATORS, FIX_HINTS } from './validators/index.ts';
import type { ValidationFinding } from './writer.ts';
const getLintLogFile = () => gbrainPath('validator-lint.jsonl');
const LINT_CONFIG_KEY = 'writer.lint_on_put_page';
export interface PostWriteLintOpts {
/** Already-prepared canonical content; validation must precede publication. */
page?: Pick<import('../types.ts').Page, 'type' | 'compiled_truth' | 'timeline' | 'frontmatter'>;
/** Override config lookup; used by tests. If true, always run. */
force?: boolean;
/** Skip file writes; used by tests. */
noLog?: boolean;
/** Exact scalar source for the page and nested validation reads. */
sourceId?: string;
/** Federated read scope; when non-empty, takes precedence over sourceId. */
sourceIds?: string[];
}
export interface PostWriteLintResult {
ran: boolean;
slug: string;
findings: ValidationFinding[];
skippedReason?: string;
}
/**
* Read the writer.lint_on_put_page flag. Returns true only when set to an
* explicit enable value; anything else (unset, 'false', '0') is false.
* Fails safe on read error.
*/
export async function isLintOnPutPageEnabled(engine: BrainEngine): Promise<boolean> {
try {
const v = await engine.getConfig(LINT_CONFIG_KEY);
if (v === null || v === undefined) return false;
const lc = v.toLowerCase();
return lc === 'true' || lc === '1' || lc === 'yes' || lc === 'on';
} catch {
return false;
}
}
/**
* Run the four built-in validators on a freshly-written page.
* Returns empty findings when:
* - flag disabled
* - page not found (shouldn't happen in normal put_page flow)
* - page has frontmatter.validate === false
*/
export async function runPostWriteLint(
engine: BrainEngine,
slug: string,
opts: PostWriteLintOpts = {},
): Promise<PostWriteLintResult> {
const enabled = opts.force ?? await isLintOnPutPageEnabled(engine);
if (!enabled) {
return { ran: false, slug, findings: [], skippedReason: 'flag_disabled' };
}
const sourceOpts = opts.sourceIds && opts.sourceIds.length > 0
? { sourceIds: opts.sourceIds }
: opts.sourceId
? { sourceId: opts.sourceId }
: undefined;
const page = opts.page ?? await engine.getPage(slug, sourceOpts);
if (!page) {
return { ran: false, slug, findings: [], skippedReason: 'page_not_found' };
}
if (page.frontmatter?.validate === false) {
return { ran: false, slug, findings: [], skippedReason: 'validate_false_frontmatter' };
}
const ctx = {
slug,
type: page.type,
compiledTruth: page.compiled_truth,
timeline: page.timeline,
frontmatter: page.frontmatter ?? {},
engine,
sourceId: opts.sourceId,
sourceIds: opts.sourceIds,
};
const findings: ValidationFinding[] = [];
for (const v of BUILTIN_VALIDATORS) {
try {
const out = await v.validate(ctx);
for (const f of out) findings.push(f);
} catch {
// Validator-level failure shouldn't break the main put_page flow;
// swallow and continue with other validators.
}
}
if (findings.length > 0 && !opts.noLog) {
writeLocalLintLog(slug, findings);
await writeIngestLog(engine, slug, findings);
}
return { ran: true, slug, findings };
}
// ---------------------------------------------------------------------------
// put_page payload plumbing (T11 writer-lint visibility)
// ---------------------------------------------------------------------------
/** top_findings cap: enough to act on, small enough for the wire. */
const TOP_FINDINGS_CAP = 5;
/** Per-finding message cap; validators already truncate embedded content. */
const FINDING_MESSAGE_MAX = 200;
export interface WriterLintFindingSummary {
validator: string;
severity: 'error' | 'warning';
line?: number;
message: string;
hint: string;
}
export interface WriterLintSummary {
error_count: number;
warning_count: number;
/** Errors-first, capped at TOP_FINDINGS_CAP, one actionable hint each. */
top_findings: WriterLintFindingSummary[];
/** True when findings beyond the cap were dropped from top_findings. */
details_truncated: boolean;
/** Finding count per validator id, e.g. { citation: 17, link: 2 }. */
by_validator: Record<string, number>;
}
/**
* The put_page `writer_lint` value: a full summary when lint ran, or the
* crash marker — distinguishable from lint-off, where the key is absent.
*/
export type WriterLintPayload = WriterLintSummary | { status: 'lint_error' };
/**
* Shape the `writer_lint` response block from the full findings array.
* Sort is stable, so within a severity findings keep validator order.
*/
export function summarizeWriterLint(findings: ValidationFinding[]): WriterLintSummary {
const errorsFirst = [...findings].sort((a, b) =>
a.severity === b.severity ? 0 : a.severity === 'error' ? -1 : 1,
);
const byValidator: Record<string, number> = {};
for (const f of findings) byValidator[f.validator] = (byValidator[f.validator] ?? 0) + 1;
return {
error_count: findings.filter(f => f.severity === 'error').length,
warning_count: findings.filter(f => f.severity === 'warning').length,
top_findings: errorsFirst.slice(0, TOP_FINDINGS_CAP).map(f => ({
validator: f.validator,
severity: f.severity,
...(f.line !== undefined ? { line: f.line } : {}),
message: truncate(f.message, FINDING_MESSAGE_MAX),
// Registry completeness is test-pinned; the fallback covers a
// non-builtin validator ever reaching this path.
hint: FIX_HINTS[f.validator] ?? 'see the validator rule for the fix',
})),
details_truncated: findings.length > TOP_FINDINGS_CAP,
by_validator: byValidator,
};
}
/**
* put_page-facing wrapper mapping every lint outcome to the response
* contract: ran (zero findings included) → full summary; did not run
* (flag off / validate:false / page missing) → undefined so the
* writer_lint key stays absent; threw → {status: 'lint_error'} so a lint
* crash is distinguishable from lint-off. Never throws.
*/
export async function writerLintForPutPage(
engine: BrainEngine,
slug: string,
opts: PostWriteLintOpts = {},
): Promise<WriterLintPayload | undefined> {
try {
const lint = await runPostWriteLint(engine, slug, opts);
if (!lint.ran) return undefined;
return summarizeWriterLint(lint.findings);
} catch {
return { status: 'lint_error' };
}
}
function truncate(s: string, n: number): string {
return s.length <= n ? s : s.slice(0, n - 3) + '...';
}
// ---------------------------------------------------------------------------
// Loggers
// ---------------------------------------------------------------------------
function writeLocalLintLog(slug: string, findings: ValidationFinding[]): void {
try {
const lintLogFile = getLintLogFile();
const dir = dirname(lintLogFile);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
const line = JSON.stringify({
ts: new Date().toISOString(),
slug,
error_count: findings.filter(f => f.severity === 'error').length,
warning_count: findings.filter(f => f.severity === 'warning').length,
findings: findings.slice(0, 20), // cap to prevent runaway log size
}) + '\n';
appendFileSync(lintLogFile, line, 'utf-8');
} catch {
// Non-fatal; logging failure shouldn't break the main flow.
}
}
async function writeIngestLog(engine: BrainEngine, slug: string, findings: ValidationFinding[]): Promise<void> {
try {
const errorCount = findings.filter(f => f.severity === 'error').length;
const warningCount = findings.filter(f => f.severity === 'warning').length;
const summary = `post-write lint: ${errorCount} error, ${warningCount} warning` +
(errorCount > 0 ? ` (top: ${findings.find(f => f.severity === 'error')!.message.slice(0, 80)})` : '');
await engine.logIngest({
source_type: 'writer_lint',
source_ref: slug,
pages_updated: [slug],
summary,
});
} catch {
// Non-fatal.
}
}