Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Tests for `o2b brain lessons` (t_1e952e43, task C2).
*
* Drives the operator verb family over the promotion kernel:
* - `candidates` is read-only and reports promotable plus
* blocked-with-reason, including the disabled state;
* - `approve` follows the install consent ladder: plan-only by default,
* headless `--apply` without `--yes` refuses with exit 6, the ledger
* row is recorded only after the rules-block write landed, and the
* approval event joins the shared log chain;
* - `deny` records without touching any rules file and suppresses the
* lesson from every later listing;
* - `refresh-blocks` is a dry run by default, is a named no-op when no
* block exists under management, never CREATES a block, drops a stale
* lesson by name, and stamps `lastPromotedAt` on what it wrote.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { computeContentHash } from "../../src/core/brain/content-hash.ts";
import { listLogDates, readLogDay } from "../../src/core/brain/log-jsonl.ts";
import {
LESSONS_APPROVALS_FILE,
lessonsApprovalsPath,
readLessonApprovals,
recordLessonApproval,
} from "../../src/core/brain/lessons-promotion.ts";
import { RULES_BLOCK_MARKERS } from "../../src/core/install/rules-block.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { appendLogEvent } from "../../src/core/brain/log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../src/core/brain/types.ts";
import { runCli } from "../helpers/run-cli.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
const SCOPE_ENV = "OPEN_SECOND_BRAIN_LESSONS_PROMOTION_SCOPES";
const PRINCIPLE = "Always run the full test suite before pushing to main";
let tmp: string;
let vault: string;
let configPath: string;
let savedScopeEnv: string | undefined;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-lessons-cli-"));
vault = join(tmp, "vault");
configPath = join(tmp, "config.yaml");
writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
bootstrapBrain(vault, { configPath });
savedScopeEnv = process.env[SCOPE_ENV];
process.env[SCOPE_ENV] = "backend";
});
afterEach(() => {
if (savedScopeEnv === undefined) delete process.env[SCOPE_ENV];
else process.env[SCOPE_ENV] = savedScopeEnv;
rmSync(tmp, { recursive: true, force: true });
});
const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath, [SCOPE_ENV]: "backend" });
function seedPreferredLesson(
slug: string,
overrides: { scope?: string; confidence?: string; principle?: string } = {},
): void {
writePreference(vault, {
slug,
topic: slug,
principle: overrides.principle ?? PRINCIPLE,
scope: overrides.scope ?? "backend",
created_at: "2026-05-01T00:00:00Z",
confirmed_at: "2026-05-02T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: "confirmed",
evidenced_by: ["[[sig-1]]"],
applied_count: 2,
violated_count: 0,
last_evidence_at: "2026-05-10T00:00:00Z",
confidence: overrides.confidence ?? "high",
} as Parameters<typeof writePreference>[1]);
appendLogEvent(
vault,
{
timestamp: "2026-05-09T00:00:00Z",
eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
body: { preference: `[[pref-${slug}]]`, artifact: "[[a.ts]]", agent: "t", result: "applied" },
},
{ deviceId: "" },
);
appendLogEvent(
vault,
{
timestamp: "2026-05-10T00:00:00Z",
eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
body: { preference: `[[pref-${slug}]]`, artifact: "[[b.ts]]", agent: "t", result: "applied" },
},
{ deviceId: "" },
);
}
const NOW_FIXTURE_MS = Date.parse("2026-05-20T00:00:00Z");
function ledgerEvents(): ReadonlyArray<string> {
const dates = listLogDates(vault);
const kinds: string[] = [];
for (const date of dates) {
for (const entry of readLogDay(vault, date).entries) kinds.push(entry.eventType);
}
return kinds;
}
describe("o2b brain lessons candidates", () => {
test("lists promotable and blocked with reasons, read-only", async () => {
seedPreferredLesson("approved-lesson");
seedPreferredLesson("norow-lesson");
recordLessonApproval(vault, {
prefId: "pref-approved-lesson",
decision: "approved",
decidedAt: "2026-05-15T00:00:00Z",
decidedBy: "yes-flag",
approvedContentHash: computeContentHash(PRINCIPLE, "backend"),
targets: ["AGENTS.md"],
blockId: "lessons",
lastPromotedAt: null,
});
const rulesBefore = existsSync(join(vault, "AGENTS.md"));
const ledgerBefore = existsSync(lessonsApprovalsPath(vault))
? readFileSync(lessonsApprovalsPath(vault), "utf8")
: null;
const out = await runCli(["brain", "lessons", "candidates", "--json"], { env: env() });
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as {
promotable: Array<{ prefId: string }>;
blocked: Array<{ prefId: string; reason: string }>;
scopes: { count: number };
};
expect(payload.promotable.map((c) => c.prefId)).toEqual(["pref-approved-lesson"]);
expect(payload.blocked).toEqual([{ prefId: "pref-norow-lesson", reason: "not_approved" }]);
expect(payload.scopes.count).toBe(1);
// Read-only: no rules file appeared, the ledger is byte-identical.
expect(existsSync(join(vault, "AGENTS.md"))).toBe(rulesBefore);
expect(
existsSync(lessonsApprovalsPath(vault))
? readFileSync(lessonsApprovalsPath(vault), "utf8")
: null,
).toBe(ledgerBefore);
});
test("promotion disabled is a named count of zero with every lesson scope-blocked", async () => {
seedPreferredLesson("disabled-lesson");
recordLessonApproval(vault, {
prefId: "pref-disabled-lesson",
decision: "approved",
decidedAt: "2026-05-15T00:00:00Z",
decidedBy: "yes-flag",
approvedContentHash: computeContentHash(PRINCIPLE, "backend"),
targets: ["AGENTS.md"],
blockId: "lessons",
lastPromotedAt: null,
});
const out = await runCli(["brain", "lessons", "candidates", "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as {
promotable: unknown[];
blocked: Array<{ reason: string }>;
scopes: { count: number };
};
expect(payload.scopes.count).toBe(0);
expect(payload.promotable).toEqual([]);
expect(payload.blocked[0]?.reason).toBe("scope_not_enabled");
});
test("a present-but-malformed scopes value is a named refusal, never a silent disabled", async () => {
// A bracket-shaped paste (`scopes: [a, b]` into the flat key) used to
// resolve exactly like an unset key; the operator could not tell
// "configured wrong" from "never configured".
seedPreferredLesson("scoped-lesson");
const out = await runCli(["brain", "lessons", "candidates", "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [SCOPE_ENV]: "[backend, testing]" },
});
expect(out.returncode).toBe(1);
expect(out.stderr).toContain("malformed");
expect(out.stderr).toContain(SCOPE_ENV);
expect(out.stderr).toContain("promotion stays disabled");
// The mutating verbs refuse the same way, before any write.
const approved = await runCli(
["brain", "lessons", "approve", "pref-scoped-lesson", "--apply", "--yes"],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [SCOPE_ENV]: "[backend]" } },
);
expect(approved.returncode).toBe(1);
expect(approved.stderr).toContain("malformed");
expect(existsSync(lessonsApprovalsPath(vault))).toBe(false);
});
});
describe("o2b brain lessons approve", () => {
test("plan-only default renders targets and writes nothing", async () => {
seedPreferredLesson("plan-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# house rules\n\nbe careful.\n");
const before = readFileSync(join(vault, "AGENTS.md"), "utf8");
const out = await runCli(["brain", "lessons", "approve", "pref-plan-lesson"], { env: env() });
expect(out.returncode).toBe(0);
expect(out.stdout).toContain("AGENTS.md");
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toBe(before);
expect(existsSync(lessonsApprovalsPath(vault))).toBe(false);
});
test("headless --apply without --yes refuses with exit 6 and writes nothing", async () => {
seedPreferredLesson("gate-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# house rules\n\nbe careful.\n");
const out = await runCli(
["brain", "lessons", "approve", "pref-gate-lesson", "--apply", "--json"],
{ env: env() },
);
expect(out.returncode).toBe(6);
const payload = JSON.parse(out.stdout) as { consent: string; written: boolean };
expect(payload.consent).toBe("headless-refused");
expect(payload.written).toBe(false);
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).not.toContain(
RULES_BLOCK_MARKERS.lessons.begin,
);
expect(existsSync(lessonsApprovalsPath(vault))).toBe(false);
});
test("--apply --yes writes the block, records the row, and appends the event", async () => {
seedPreferredLesson("ok-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# house rules\n\nbe careful.\n");
const out = await runCli(
[
"brain",
"lessons",
"approve",
"pref-ok-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(out.returncode).toBe(0);
const rules = readFileSync(join(vault, "AGENTS.md"), "utf8");
expect(rules).toContain(RULES_BLOCK_MARKERS.lessons.begin);
expect(rules).toContain(PRINCIPLE);
expect(rules).toContain("# house rules");
const rows = readLessonApprovals(vault);
expect(rows.length).toBe(1);
expect(rows[0]?.decision).toBe("approved");
expect(rows[0]?.prefId).toBe("pref-ok-lesson");
expect(rows[0]?.targets).toEqual(["AGENTS.md"]);
expect(rows[0]?.approvedContentHash).toBe(computeContentHash(PRINCIPLE, "backend"));
expect(ledgerEvents()).toContain(BRAIN_LOG_EVENT_KIND.lessonsApproved);
// A rerun of candidates shows the lesson promotable.
const list = await runCli(["brain", "lessons", "candidates", "--json"], { env: env() });
const payload = JSON.parse(list.stdout) as { promotable: Array<{ prefId: string }> };
expect(payload.promotable.map((c) => c.prefId)).toEqual(["pref-ok-lesson"]);
});
test("an unknown pref id is a named error, exit 2", async () => {
const out = await runCli(["brain", "lessons", "approve", "pref-absent", "--apply", "--yes"], {
env: env(),
});
expect(out.returncode).toBe(2);
expect(out.stderr).toContain("pref-absent");
});
test("a lesson whose scope could forge a block marker refuses the approve by name", async () => {
// The enabled-scope twin carries the marker-shaped scope, so the
// lesson QUALIFIES - and the render must still refuse it, before any
// consent, write or ledger row. writePreference refuses a marker-
// shaped scope at write time, so the fixture seeds a normal file and
// then edits the persisted frontmatter directly: the preference file
// is vault state that can arrive by other means than this build's
// writer, which is exactly the shape the render must refuse.
const forgedScope = RULES_BLOCK_MARKERS.lessons.end;
seedPreferredLesson("forge-lesson");
const prefPath = join(vault, "Brain", "preferences", "pref-forge-lesson.md");
const persisted = readFileSync(prefPath, "utf8");
expect(persisted).toContain("scope:");
writeFileSync(prefPath, persisted.replace(/scope:.*/, `scope: "${forgedScope}"`));
writeFileSync(join(vault, "AGENTS.md"), "# house rules\n\nbe careful.\n");
const rulesBefore = readFileSync(join(vault, "AGENTS.md"), "utf8");
const planned = await runCli(["brain", "lessons", "approve", "pref-forge-lesson"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [SCOPE_ENV]: forgedScope },
});
expect(planned.returncode).toBe(1);
expect(planned.stderr).toContain("pref-forge-lesson");
expect(planned.stderr).toContain("scope");
const applied = await runCli(
[
"brain",
"lessons",
"approve",
"pref-forge-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [SCOPE_ENV]: forgedScope } },
);
expect(applied.returncode).toBe(1);
expect(applied.stderr).toContain("pref-forge-lesson");
// Nothing was written: no block, no ledger row.
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toBe(rulesBefore);
expect(existsSync(lessonsApprovalsPath(vault))).toBe(false);
});
test("a refusal on the second target refuses the whole approve before any write", async () => {
// The multi-target approve must compute the plan for ALL targets
// first (the installer's dry-pass discipline): a refusal on the
// second target must not leave the first written and unmanaged.
seedPreferredLesson("multi-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# rules\n");
writeFileSync(
join(vault, "CLAUDE.md"),
[
"# claude rules",
"",
RULES_BLOCK_MARKERS.lessons.begin,
"hand-written lessons content",
RULES_BLOCK_MARKERS.lessons.end,
"",
].join("\n"),
);
const out = await runCli(
[
"brain",
"lessons",
"approve",
"pref-multi-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
"--target",
"CLAUDE.md",
],
{ env: env() },
);
expect(out.returncode).toBe(1);
expect(out.stderr).toContain("CLAUDE.md");
expect(out.stderr).toContain("user-modified-block");
expect(out.stderr).toContain("nothing was written");
// Neither target moved and no approval row was recorded.
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toBe("# rules\n");
expect(readFileSync(join(vault, "CLAUDE.md"), "utf8")).toContain(
"hand-written lessons content",
);
expect(existsSync(lessonsApprovalsPath(vault))).toBe(false);
});
});
describe("o2b brain lessons deny", () => {
test("deny records the decision without writing any rules file", async () => {
seedPreferredLesson("deny-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# house rules\n\nbe careful.\n");
const before = readFileSync(join(vault, "AGENTS.md"), "utf8");
const out = await runCli(["brain", "lessons", "deny", "pref-deny-lesson", "--apply", "--yes"], {
env: env(),
});
expect(out.returncode).toBe(0);
const rows = readLessonApprovals(vault);
expect(rows.length).toBe(1);
expect(rows[0]?.decision).toBe("denied");
expect(rows[0]?.targets).toEqual([]);
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toBe(before);
expect(ledgerEvents()).toContain(BRAIN_LOG_EVENT_KIND.lessonsDenied);
const list = await runCli(["brain", "lessons", "candidates", "--json"], { env: env() });
const payload = JSON.parse(list.stdout) as {
blocked: Array<{ prefId: string; reason: string }>;
};
expect(payload.blocked).toEqual([{ prefId: "pref-deny-lesson", reason: "denied" }]);
});
test("headless deny without --yes refuses with exit 6", async () => {
seedPreferredLesson("deny-gate");
const out = await runCli(["brain", "lessons", "deny", "pref-deny-gate", "--apply", "--json"], {
env: env(),
});
expect(out.returncode).toBe(6);
expect(existsSync(lessonsApprovalsPath(vault))).toBe(false);
});
});
describe("o2b brain lessons refresh-blocks", () => {
test("is a named no-op when no block exists under management", async () => {
seedPreferredLesson("lonely-lesson");
recordLessonApproval(vault, {
prefId: "pref-lonely-lesson",
decision: "approved",
decidedAt: "2026-05-15T00:00:00Z",
decidedBy: "yes-flag",
approvedContentHash: computeContentHash(PRINCIPLE, "backend"),
targets: ["AGENTS.md"],
blockId: "lessons",
lastPromotedAt: null,
});
const out = await runCli(["brain", "lessons", "refresh-blocks", "--apply", "--yes"], {
env: env(),
});
expect(out.returncode).toBe(0);
expect(out.stdout).toMatch(/no lessons block under management/i);
expect(existsSync(join(vault, "AGENTS.md"))).toBe(false);
});
test("updates an existing block, drops a stale lesson by name, and stamps lastPromotedAt", async () => {
seedPreferredLesson("stale-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# house rules\n");
const approval = await runCli(
[
"brain",
"lessons",
"approve",
"pref-stale-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(approval.returncode).toBe(0);
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toContain(PRINCIPLE);
// The operator edits the approved preference: the pinned hash goes stale.
const prefPath = join(vault, "Brain", "preferences", "pref-stale-lesson.md");
const prefBytes = readFileSync(prefPath, "utf8");
writeFileSync(prefPath, prefBytes.replace(PRINCIPLE, `${PRINCIPLE}, amended`));
const refresh = await runCli(["brain", "lessons", "refresh-blocks", "--apply", "--yes"], {
env: env(),
});
expect(refresh.returncode).toBe(0);
expect(refresh.stdout).toContain("pref-stale-lesson");
const rules = readFileSync(join(vault, "AGENTS.md"), "utf8");
expect(rules).not.toContain(PRINCIPLE);
const rows = readLessonApprovals(vault);
expect(rows[0]?.lastPromotedAt).not.toBeNull();
expect(ledgerEvents()).toContain(BRAIN_LOG_EVENT_KIND.lessonsPromoted);
});
test("the refresh result names dropped lessons instead of truncating silently", async () => {
// Under the shipped wiring the digest cap and the block cap read the
// same `lessons.limit`, so the live renders drop nothing - the field
// is the named surface the render reports its cut through
// (`renderLessonsBlockWithDrops` pins the non-empty case at the
// kernel). The verb output and JSON carry it either way, so a future
// divergence between the two bounds can never truncate silently.
seedPreferredLesson("named-drop-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# rules\n");
const approval = await runCli(
[
"brain",
"lessons",
"approve",
"pref-named-drop-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(approval.returncode).toBe(0);
const refresh = await runCli(
["brain", "lessons", "refresh-blocks", "--apply", "--yes", "--json"],
{
env: env(),
},
);
expect(refresh.returncode).toBe(0);
const payload = JSON.parse(refresh.stdout) as {
dropped: ReadonlyArray<{ target: string; ids: ReadonlyArray<string> }>;
};
expect(payload.dropped).toEqual([]);
});
test("skips a target whose block is absent by name and never creates it", async () => {
seedPreferredLesson("two-file-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# rules\n");
const approval = await runCli(
[
"brain",
"lessons",
"approve",
"pref-two-file-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(approval.returncode).toBe(0);
// Widen the row's targets to a file that carries no block.
const rows = readLessonApprovals(vault);
recordLessonApproval(vault, { ...rows[0]!, targets: ["AGENTS.md", "CLAUDE.md"] });
const claudePath = join(vault, "CLAUDE.md");
expect(existsSync(claudePath)).toBe(false);
const refresh = await runCli(["brain", "lessons", "refresh-blocks", "--apply", "--yes"], {
env: env(),
});
expect(refresh.returncode).toBe(0);
expect(refresh.stdout).toContain("CLAUDE.md");
expect(existsSync(claudePath)).toBe(false);
});
test("the default run is a dry preview that writes nothing", async () => {
seedPreferredLesson("dry-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# rules\n");
const approval = await runCli(
[
"brain",
"lessons",
"approve",
"pref-dry-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(approval.returncode).toBe(0);
const prefPath = join(vault, "Brain", "preferences", "pref-dry-lesson.md");
writeFileSync(
prefPath,
readFileSync(prefPath, "utf8").replace(PRINCIPLE, `${PRINCIPLE} with edits`),
);
const before = readFileSync(join(vault, "AGENTS.md"), "utf8");
const ledgerBefore = readFileSync(lessonsApprovalsPath(vault), "utf8");
const dry = await runCli(["brain", "lessons", "refresh-blocks"], { env: env() });
expect(dry.returncode).toBe(0);
expect(readFileSync(join(vault, "AGENTS.md"), "utf8")).toBe(before);
expect(readFileSync(lessonsApprovalsPath(vault), "utf8")).toBe(ledgerBefore);
});
test("a future-stamped lastPromotedAt is untrusted: the hand-edited block refuses without --force", async () => {
// The promotion stamp lives in agent-writable ledger state. Stamping
// it into the future would make every later operator hand-edit read
// as a canonical move under an untouched file, so the gate must
// treat it as no record - which refuses the removal path too.
seedPreferredLesson("future-stamp-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# rules\n");
const approval = await runCli(
[
"brain",
"lessons",
"approve",
"pref-future-stamp-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(approval.returncode).toBe(0);
// Re-stamp the row into the future, far past the clock-skew allowance.
const rows = readLessonApprovals(vault);
recordLessonApproval(vault, {
...rows[0]!,
lastPromotedAt: new Date(Date.now() + 10 * 60_000).toISOString(),
});
// The approved text moves, so nothing qualifies any more and the
// refresh would REMOVE the block; a hand edit makes the file the
// operator's, not the writer's.
const rulesPath = join(vault, "AGENTS.md");
writeFileSync(
rulesPath,
readFileSync(rulesPath, "utf8").replace(PRINCIPLE, "HAND EDITED LINE"),
);
const refused = await runCli(["brain", "lessons", "refresh-blocks", "--apply", "--yes"], {
env: env(),
});
expect(refused.returncode).toBe(1);
expect(refused.stderr).toContain("user-modified-block");
expect(readFileSync(rulesPath, "utf8")).toContain("HAND EDITED LINE");
// --force stays the documented override.
const forced = await runCli(
["brain", "lessons", "refresh-blocks", "--apply", "--yes", "--force"],
{ env: env() },
);
expect(forced.returncode).toBe(0);
expect(existsSync(rulesPath) ? readFileSync(rulesPath, "utf8") : "").not.toContain(
"HAND EDITED LINE",
);
});
test("a hand-edited block refuses the refresh by name; --force overrides", async () => {
seedPreferredLesson("hand-lesson");
writeFileSync(join(vault, "AGENTS.md"), "# rules\n");
const approval = await runCli(
[
"brain",
"lessons",
"approve",
"pref-hand-lesson",
"--apply",
"--yes",
"--target",
"AGENTS.md",
],
{ env: env() },
);
expect(approval.returncode).toBe(0);
// A second approved lesson changes the canonical body; a hand edit to
// the block makes the file NEWER than the promotion stamp.
seedPreferredLesson("hand-lesson-2");
recordLessonApproval(vault, {
prefId: "pref-hand-lesson-2",
decision: "approved",
decidedAt: "2026-05-16T00:00:00Z",
decidedBy: "yes-flag",
approvedContentHash: computeContentHash(
"Always run the full test suite before pushing to main",
"backend",
),
targets: ["AGENTS.md"],
blockId: "lessons",
lastPromotedAt: null,
});
const rulesPath = join(vault, "AGENTS.md");
// The shared writer grants hand edits a 1 s mtime slack over the
// recorded promotion stamp, and the stamp itself truncates to the
// second, so an immediate edit would be indistinguishable from the
// writer's own write. Sleep past stamp rounding (up to 999 ms) plus
// the writer slack (1000 ms) so this edit is decided by intent, not
// by where the second boundary happened to fall.
await Bun.sleep(2_200);
writeFileSync(
rulesPath,
readFileSync(rulesPath, "utf8").replace(PRINCIPLE, "HAND EDITED LINE"),
);
const refused = await runCli(["brain", "lessons", "refresh-blocks", "--apply", "--yes"], {
env: env(),
});
expect(refused.returncode).not.toBe(0);
expect(refused.stderr).toContain("user-modified-block");
const forced = await runCli(
["brain", "lessons", "refresh-blocks", "--apply", "--yes", "--force"],
{ env: env() },
);
expect(forced.returncode).toBe(0);
const rules = readFileSync(rulesPath, "utf8");
expect(rules).toContain("pref-hand-lesson");
expect(rules).not.toContain("HAND EDITED LINE");
});
});
describe("o2b brain lessons usage", () => {
test("a missing subcommand is a usage error", async () => {
const out = await runCli(["brain", "lessons"], { env: env() });
expect(out.returncode).toBe(2);
expect(out.stderr).toContain("candidates");
});
});
describe("the docs name the lane (docs drift fails a test)", () => {
const repoRoot = join(import.meta.dir, "..", "..");
const read = (rel: string): string => readFileSync(join(repoRoot, rel), "utf8");
test("the cli reference names the verb family, the approval tier and the trust boundary", () => {
const cli = read("docs/cli-reference.md");
expect(cli).toContain("o2b brain lessons");
for (const verb of ["candidates", "approve", "deny", "refresh-blocks"]) {
expect(`${verb} documented: ${cli.includes(verb)}`).toBe(`${verb} documented: true`);
}
expect(cli).toContain("operator-approved lesson promotion");
// The trust boundary is stated in the docs, not only in the docblocks.
expect(cli).toContain("no MCP tool exposes this verb family");
});
test("the observability guide names the audit events and the trust boundary", () => {
const obs = read("docs/observability.md");
for (const kind of ["lessons-approved", "lessons-denied", "lessons-promoted"]) {
expect(`${kind} documented: ${obs.includes(kind)}`).toBe(`${kind} documented: true`);
}
expect(obs).toContain("Operator CLI only");
expect(obs).toContain("no agent-facing surface can mint these events");
expect(obs).toContain("stale-lessons");
});
});
describe("surface registrations", () => {
test("the ledger fixture name and the NOW fixture stay honest", () => {
expect(LESSONS_APPROVALS_FILE).toBe("lessons-approvals.json");
expect(Number.isFinite(NOW_FIXTURE_MS)).toBe(true);
});
});