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
/**
* `o2b brain lessons` - operator-approved lesson promotion (t_1e952e43,
* task C2). Thin CLI wrapper over the promotion kernel
* (`src/core/brain/lessons-promotion.ts`); qualification, rendering and
* the approval ledger all live there. This verb adds only the operator
* surfaces: listing, the consent ladder, and managed-block maintenance.
*
* Subcommands:
*
* - `candidates` is READ-ONLY: the promotable set, every blocked lesson
* with its single named reason, and the resolved promotion scopes.
* It writes nothing - no rules file, no ledger, no log event.
* - `approve <pref-id>` follows the install consent ladder: plan-only
* by default (target files and the block diff), `--apply` executes,
* a headless `--apply` without `--yes` refuses with exit 6, an
* interactive `--apply` without `--yes` asks once. Before any write,
* the plan for EVERY affected target is computed and every writer
* refusal is fired (the same dry pre-pass refresh-blocks runs), so a
* refusal on one target refuses the whole verb and no target is left
* written and unmanaged. The ledger row is recorded only AFTER the
* rules-block writes landed, so a refused approve lifts nothing -
* not even a prior denial. Every rules-file byte goes through the
* shared writer (`src/core/install/rules-block.ts`); this verb never
* writes a rules file itself.
* - `deny <pref-id>` records the decision and appends the log event,
* gated by the same ladder because a denial is a state change too;
* it never writes a rules file.
* - `refresh-blocks` re-renders the managed lessons blocks from the
* currently qualified set. It is a dry preview by default, is a
* named no-op when no block exists under management (it never
* CREATES a block - creation is approve's write), drops a lesson
* whose approval went stale by name, and stamps `lastPromotedAt`
* on the rows whose content a write delivered.
*
* Trust boundary: these verbs are operator-only. No MCP tool and no hook
* or dream path reaches them; an agent-facing surface that could approve
* its own lessons is a design defect regardless of what tests say.
*/
import { existsSync, statSync } from "node:fs";
import { join } from "node:path";
import { computeContentHash } from "../../../core/brain/content-hash.ts";
import {
LESSON_PROMOTION_BLOCKED,
currentApprovalFor,
gatherLessonsPromotionInputs,
lessonPromotionCandidates,
lessonsBlockLimit,
markLessonPromoted,
readLessonApprovals,
recordLessonApproval,
renderLessonsBlockWithDrops,
type LessonApprovalRow,
type LessonPromotionCandidate,
type RenderedLessonsBlock,
} from "../../../core/brain/lessons-promotion.ts";
import { appendLogEvent } from "../../../core/brain/log.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { BRAIN_LOG_EVENT_KIND, type BrainLogEventKind } from "../../../core/brain/types.ts";
import { AGENT_INSTRUCTION_FILES } from "../../../core/brain/writeback-contract.ts";
import { renderPrefLink } from "../../../core/brain/wikilink.ts";
import {
FUTURE_ANCHOR_ALLOWANCE_MS,
RULES_BLOCK_ERROR_KIND,
RULES_BLOCK_ID,
RulesBlockError,
readRulesBlock,
removeRulesBlock,
writeRulesBlock,
} from "../../../core/install/rules-block.ts";
import {
brainVerbContext,
fail,
ok,
okJson,
parse,
readSingleLine,
renderUnifiedDiff,
resolveBrainAgent,
usageError,
writeJson,
} from "../helpers.ts";
/**
* Every code this verb family returns, named once so the docblock, the
* returns and the tests read one table. `consentRefused` is 6, the
* install ladder's reserved verdict (`INSTALL_EXIT.consentRefused`), so
* every consent-bearing surface in the tool answers with the same number.
*/
export const LESSONS_EXIT = Object.freeze({
ok: 0,
runtimeError: 1,
usage: 2,
consentRefused: 6,
} as const);
/**
* Clock slack between the ledger's promotion stamp and a file mtime,
* mirroring the rules-block writer's own slack: a write landing within a
* second of its record must not read as a later hand edit. The writer
* enforces this on its write path; the same slack guards the removal
* path here, where the writer deliberately carries no divergence gate.
*/
const REMOVAL_MTIME_SLACK_MS = 1000;
/** One planned change to one managed rules file, before consent. */
interface RefreshAction {
readonly target: string;
readonly kind: "write" | "remove";
/** The canonical body, for `write` actions. */
readonly body: string;
/** The ownership stamp the writer's hand-edit gate compares against. */
readonly installedAtMs: number | null;
/** Qualified lessons the `lessons.limit` cut dropped from this render. */
readonly droppedIds: ReadonlyArray<string>;
}
/** A target that carries no block refresh may touch, reported by name. */
interface RefreshSkip {
readonly target: string;
readonly reason: string;
}
export async function cmdBrainLessons(argv: string[]): Promise<number> {
const sub = argv[0];
const rest = argv.slice(1);
switch (sub) {
case "candidates":
return lessonsCandidates(rest);
case "approve":
return await lessonsApprove(rest);
case "deny":
return await lessonsDeny(rest);
case "refresh-blocks":
return await lessonsRefreshBlocks(rest);
default:
return usageError(
"brain lessons requires a subcommand: candidates | approve <pref-id> | deny <pref-id> | " +
"refresh-blocks",
);
}
}
// ----- Shared helpers ---------------------------------------------------------
/** The qualification split plus the vault inputs it derived from. */
interface Qualification {
readonly inputs: ReturnType<typeof gatherLessonsPromotionInputs>;
readonly promotable: ReadonlyArray<LessonPromotionCandidate>;
readonly blocked: ReadonlyArray<{ readonly prefId: string; readonly reason: string }>;
}
/** Gather the vault inputs and split qualification against `approvals`. */
function qualify(
vault: string,
configPath: string,
approvals: ReadonlyArray<LessonApprovalRow>,
): Qualification {
const inputs = gatherLessonsPromotionInputs(vault, { configPath });
const { promotable, blocked } = lessonPromotionCandidates(
inputs.preferences,
inputs.lessons,
approvals,
{ enabledScopes: inputs.scopes.scopes },
);
return { inputs, promotable, blocked };
}
/**
* The agent rules files a promotion may touch, in the fixed
* `AGENT_INSTRUCTION_FILES` order. An explicit `--target` must name one
* of them - an arbitrary path would put a rules-file write outside the
* audited file set. The default is the files that exist at the vault
* root (discovery by existence, never glob), so a plain `approve` plans
* against the files the operator actually has.
*/
function resolveTargets(
vault: string,
explicit: ReadonlyArray<string>,
): { readonly targets: ReadonlyArray<string> } | { readonly error: string } {
for (const name of explicit) {
if (!(AGENT_INSTRUCTION_FILES as ReadonlyArray<string>).includes(name)) {
return {
error: `--target must be one of ${AGENT_INSTRUCTION_FILES.join(", ")}, got ${name}`,
};
}
}
if (explicit.length > 0) return { targets: explicit };
return { targets: AGENT_INSTRUCTION_FILES.filter((name) => existsSync(join(vault, name))) };
}
/**
* The qualified lessons whose approval covers `file`: promotion honours
* the per-file targets an approval named, so a lesson approved for one
* rules file never rides into another.
*/
function qualifiedForFile(
promotable: ReadonlyArray<LessonPromotionCandidate>,
approvals: ReadonlyArray<LessonApprovalRow>,
file: string,
): ReadonlyArray<LessonPromotionCandidate> {
return promotable.filter((candidate) => {
const row = currentApprovalFor(approvals, candidate.prefId);
return row !== null && row.decision === "approved" && row.targets.includes(file);
});
}
/**
* Canonical block render for one target file, or null when nothing
* qualifies. The full render (body plus the cap's named drops) so every
* verb can report a lesson the `lessons.limit` cut instead of letting it
* leave the block silently.
*/
function canonicalRenderFor(
promotable: ReadonlyArray<LessonPromotionCandidate>,
approvals: ReadonlyArray<LessonApprovalRow>,
file: string,
vault: string,
): RenderedLessonsBlock | null {
const qualified = qualifiedForFile(promotable, approvals, file);
if (qualified.length === 0) return null;
return renderLessonsBlockWithDrops(qualified, { limit: lessonsBlockLimit(vault) });
}
/** Canonical block body for one target file, or null when nothing qualifies. */
function canonicalBodyFor(
promotable: ReadonlyArray<LessonPromotionCandidate>,
approvals: ReadonlyArray<LessonApprovalRow>,
file: string,
vault: string,
): string | null {
return canonicalRenderFor(promotable, approvals, file, vault)?.body ?? null;
}
/** The consent verdict this invocation will record, in the shared vocabulary. */
function consentVerdict(yes: boolean): LessonApprovalRow["decidedBy"] {
return yes ? "yes-flag" : "interactive-yes";
}
/**
* The install ladder's headless gate: an `--apply` without `--yes` on a
* `--json` or non-TTY run refuses before anything is written, with the
* reserved `headless-refused` verdict on the stream a headless consumer
* parses (stdout under `--json`, stderr otherwise) and exit 6.
*/
function refuseHeadless(json: boolean, context: string): number {
const refusal =
`this command requires --yes in non-interactive mode (--json or non-TTY stdin); ` +
`nothing was written (${context})`;
if (json) {
writeJson({ consent: "headless-refused", written: false, error: refusal });
} else {
process.stderr.write(`error: ${refusal}\n`);
}
return LESSONS_EXIT.consentRefused;
}
/**
* One rules-block writer refusal, named by kind so failures stay legible
* ("user-modified-block: ..."). Duck-typed on the `kind` property rather
* than only `instanceof`, so the name survives even when the error object
* crossed a module-registry boundary.
*/
function rulesBlockErrorLine(err: unknown): string {
if (err instanceof RulesBlockError) return `${err.kind}: ${err.message}`;
if (
typeof err === "object" &&
err !== null &&
typeof (err as { kind?: unknown }).kind === "string" &&
err instanceof Error
) {
return `${(err as unknown as { kind: string }).kind}: ${err.message}`;
}
return err instanceof Error ? err.message : String(err);
}
/**
* The latest promotion stamp among the approval rows covering `file`, as
* epoch ms - the ownership record the writer's hand-edit gate compares
* the file mtime against. No stamped row returns null, which makes the
* writer refuse to overwrite a diverged block nobody recorded. A stamp
* further than the shared clock-skew allowance into the future is
* ignored as if unparsable: the ledger is agent-writable state, and a
* future-stamped record would make every operator hand-edit read as a
* canonical move under an untouched file - the fail-closed direction is
* "no trustworthy record".
*/
function installedAtMsFor(
approvals: ReadonlyArray<LessonApprovalRow>,
file: string,
): number | null {
let latest: number | null = null;
for (const row of approvals) {
if (row.decision !== "approved" || !row.targets.includes(file)) continue;
if (row.lastPromotedAt === null) continue;
const ms = Date.parse(row.lastPromotedAt);
if (!Number.isFinite(ms)) continue;
if (ms > Date.now() + FUTURE_ANCHOR_ALLOWANCE_MS) continue;
if (latest === null || ms > latest) latest = ms;
}
return latest;
}
/**
* Whether a managed file looks hand-edited since its last recorded
* promotion, with the same slack the writer grants its own writes. A
* null stamp means no recorded promotion, so the block cannot be proven
* ours and counts as touched - the fail-closed direction.
*/
function touchedSincePromotion(installedAtMs: number | null, file: string): boolean {
if (installedAtMs === null) return true;
try {
const mtimeMs = statSync(file, { throwIfNoEntry: false })?.mtimeMs;
if (mtimeMs === undefined) return true;
return mtimeMs > installedAtMs + REMOVAL_MTIME_SLACK_MS;
} catch {
return true;
}
}
/** Append a lessons log event; a failed append warns, it never fails the verb. */
function appendLessonsEvent(
vault: string,
eventType: BrainLogEventKind,
body: Record<string, string>,
): void {
try {
appendLogEvent(
vault,
{ timestamp: isoSecond(new Date()), eventType, body },
{ failOpen: true },
);
} catch (err) {
process.stderr.write(`warning: append ${eventType} log failed: ${(err as Error).message}\n`);
}
}
/** The per-target block diff lines an approve plan (or prompt) shows. */
function approvePlanLines(
vault: string,
prefId: string,
promotable: ReadonlyArray<LessonPromotionCandidate>,
approvals: ReadonlyArray<LessonApprovalRow>,
targets: ReadonlyArray<string>,
): string[] {
const lines: string[] = [
`approve plan for ${prefId} (nothing written until --apply):`,
` targets: ${targets.join(", ")}`,
];
for (const target of targets) {
const file = join(vault, target);
const body = canonicalBodyFor(promotable, approvals, target, vault);
const current = readRulesBlock(file, RULES_BLOCK_ID.lessons);
if (body === null) {
lines.push(` ${target}: no qualified lesson covers this file (no change)`);
continue;
}
if (current === null) {
lines.push(` ${target}: creates the managed lessons block:`);
lines.push(indentDiff(renderUnifiedDiff("", body, `${target} lessons block`)));
continue;
}
if (current.replace(/\s+$/, "") === body.replace(/\s+$/, "")) {
lines.push(` ${target}: block already current (no change)`);
continue;
}
lines.push(` ${target}: updates the managed lessons block:`);
lines.push(indentDiff(renderUnifiedDiff(current, body, `${target} lessons block`)));
}
return lines;
}
/** Indent a unified diff one level, so plan output nests under its file line. */
function indentDiff(diff: string): string {
return diff
.split("\n")
.map((line) => ` ${line}`)
.join("\n");
}
/** The provisional row a qualification simulation runs against. */
function provisionalRow(
prefId: string,
targets: ReadonlyArray<string>,
liveHash: string,
): LessonApprovalRow {
return {
prefId,
decision: "approved",
decidedAt: isoSecond(new Date()),
decidedBy: "yes-flag",
approvedContentHash: liveHash,
targets,
blockId: RULES_BLOCK_ID.lessons,
lastPromotedAt: null,
};
}
/** One rules-file write through the K1 writer, with the ownership stamp. */
function writeBlock(
file: string,
body: string,
opts: {
readonly dryRun: boolean;
readonly force: boolean;
readonly installedAtMs: number | null;
},
): { readonly changed: boolean } {
const result = writeRulesBlock(file, RULES_BLOCK_ID.lessons, body, {
dryRun: opts.dryRun,
force: opts.force,
...(opts.installedAtMs !== null ? { installedAtMs: opts.installedAtMs } : {}),
});
return { changed: result.changed };
}
// ----- candidates -------------------------------------------------------------
function lessonsCandidates(argv: string[]): number {
const { flags } = parse(argv, {
vault: { type: "string" },
json: { type: "boolean" },
});
const { config, vault } = brainVerbContext(flags);
const json = flags["json"] === true;
const ledger = readLessonApprovals(vault);
// A malformed promotion scopes value is a named refusal, never a
// silent "disabled": the operator must tell configured-wrong from
// never-configured.
let split: Qualification;
try {
split = qualify(vault, config, ledger);
} catch (err) {
return fail(rulesBlockErrorLine(err));
}
const { inputs, promotable, blocked } = split;
if (json) {
okJson({
command: "brain lessons candidates",
promotable: promotable.map((candidate) => ({
prefId: candidate.prefId,
principle: candidate.principle,
scope: candidate.scope,
tier: candidate.tier,
confidence: candidate.confidence,
})),
blocked: blocked.map((entry) => ({ prefId: entry.prefId, reason: entry.reason })),
scopes: { count: inputs.scopes.count, origin: inputs.scopes.origin },
});
} else {
const lines = [
`promotion scopes: ${inputs.scopes.count === 0 ? "(none - promotion disabled)" : inputs.scopes.scopes.join(", ")}` +
` (origin: ${inputs.scopes.origin})`,
`promotable: ${promotable.length}; blocked: ${blocked.length}`,
];
for (const candidate of promotable) {
lines.push(
` promotable ${candidate.prefId} (scope: ${candidate.scope}, tier: ${candidate.tier}, ` +
`confidence: ${candidate.confidence})`,
);
}
for (const entry of blocked) {
lines.push(` blocked ${entry.prefId} (${entry.reason})`);
}
ok(lines.join("\n"));
}
return LESSONS_EXIT.ok;
}
// ----- approve ----------------------------------------------------------------
async function lessonsApprove(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
target: { type: "string-array" },
apply: { type: "boolean" },
yes: { type: "boolean" },
force: { type: "boolean" },
json: { type: "boolean" },
});
const apply = flags["apply"] === true;
const yes = flags["yes"] === true;
const force = flags["force"] === true;
const json = flags["json"] === true;
const rawId = positional[0]?.trim() ?? "";
if (rawId === "") {
return usageError("brain lessons approve requires a preference id: approve <pref-id>");
}
const { config, vault } = brainVerbContext(flags);
const agent = resolveBrainAgent(flags, config);
const prefId = rawId.startsWith("pref-") ? rawId : `pref-${rawId}`;
const targets = resolveTargets(vault, (flags["target"] as ReadonlyArray<string>) ?? []);
if ("error" in targets) return usageError(targets.error);
const ledger = readLessonApprovals(vault);
const previous = currentApprovalFor(ledger, prefId);
// A malformed promotion scopes value refuses the verb by name, before
// any simulation, write or ledger row (see resolvePromotionScopesStrict).
let inputs: ReturnType<typeof gatherLessonsPromotionInputs>;
try {
inputs = gatherLessonsPromotionInputs(vault, { configPath: config });
} catch (err) {
return fail(rulesBlockErrorLine(err));
}
const pref = inputs.preferences.find((entry) => entry.id === prefId);
if (pref === undefined) {
process.stderr.write(
`error: no readable preference named ${prefId} under ${join(vault, "Brain", "preferences")}\n`,
);
return LESSONS_EXIT.usage;
}
if (targets.targets.length === 0) {
return fail(
`no agent rules file found at the vault root (${AGENT_INSTRUCTION_FILES.join(", ")}); ` +
"pass --target to name one",
);
}
const liveHash = computeContentHash(pref.principle, pref.scope);
// The decision is simulated first - a provisional approved row pinning
// the live hash replaces any prior row (the state table's latest
// decision wins, so a re-approve lifts a denial) - so the verb names
// the gate that still refuses BEFORE any ledger row or log event is
// recorded. An approval never rescues an unqualified lesson.
const simulated = [
...ledger.filter((row) => row.prefId !== prefId),
provisionalRow(prefId, targets.targets, liveHash),
];
const sim = lessonPromotionCandidates(inputs.preferences, inputs.lessons, simulated, {
enabledScopes: inputs.scopes.scopes,
});
const verdict = sim.blocked.find((entry) => entry.prefId === prefId);
if (verdict !== undefined) {
return fail(
`${prefId} is not promotable: ${verdict.reason} - approve records an approval only for a ` +
"lesson that qualifies now (confirmed, high confidence, preferred tier, enabled scope)",
);
}
// The plan render is a refusal surface too (a target with malformed
// markers, or a lesson whose scope cannot render as one block line):
// it refuses BEFORE consent, never with a crash past it.
let planLines: string[];
try {
planLines = approvePlanLines(vault, prefId, sim.promotable, simulated, targets.targets);
} catch (err) {
return fail(rulesBlockErrorLine(err));
}
if (!apply) {
if (json) {
writeJson({
command: "brain lessons approve",
prefId,
apply: false,
targets: targets.targets,
plan: planLines,
});
} else {
ok(planLines.join("\n"));
}
return LESSONS_EXIT.ok;
}
// Consent above the write lane, the install ladder verbatim.
if (!yes) {
if (json || !process.stdin.isTTY) {
return refuseHeadless(json, `approving ${prefId} into agent rules files`);
}
process.stderr.write(planLines.join("\n") + "\n");
process.stderr.write("Proceed? [y/N] ");
const ans = await readSingleLine();
if (ans.trim().toLowerCase() !== "y" && ans.trim().toLowerCase() !== "yes") {
ok("approval cancelled; nothing was written");
return LESSONS_EXIT.ok;
}
}
// The dry pre-pass, the same pure-plan discipline the installer and
// refresh-blocks hold: the plan for EVERY affected target is computed
// and every writer refusal is fired BEFORE any write lands. A refusal
// on any target refuses the whole verb, so a multi-target approve can
// never leave an earlier target written, approved-shaped, and managed
// by nothing (the ledger row lands only after every write succeeds).
const prePassRefusals: string[] = [];
for (const target of targets.targets) {
let body: string | null;
try {
body = canonicalBodyFor(sim.promotable, simulated, target, vault);
} catch (err) {
prePassRefusals.push(`${target}: ${rulesBlockErrorLine(err)}`);
continue;
}
if (body === null) continue; // unreachable: the approved lesson qualifies
try {
writeBlock(join(vault, target), body, {
dryRun: true,
force,
installedAtMs: installedAtMsFor(ledger, target),
});
} catch (err) {
prePassRefusals.push(`${target}: ${rulesBlockErrorLine(err)}`);
}
}
if (prePassRefusals.length > 0) {
return fail(
`approve refused before any write:\n` +
prePassRefusals.map((line) => ` ${line}`).join("\n") +
"\nnothing was written and no approval was recorded",
);
}
const written: string[] = [];
try {
for (const target of targets.targets) {
const body = canonicalBodyFor(sim.promotable, simulated, target, vault);
if (body === null) continue; // unreachable: the approved lesson qualifies
const result = writeBlock(join(vault, target), body, {
dryRun: false,
force,
installedAtMs: installedAtMsFor(ledger, target),
});
if (result.changed) written.push(target);
}
} catch (err) {
return fail(rulesBlockErrorLine(err));
}
// The row lands only after every write succeeded: a refused approve
// lifts nothing, and a denial that was on disk stays on disk.
const now = new Date();
const consent = consentVerdict(yes);
recordLessonApproval(vault, {
prefId,
decision: "approved",
decidedAt: isoSecond(now),
decidedBy: consent,
approvedContentHash: liveHash,
targets: targets.targets,
blockId: RULES_BLOCK_ID.lessons,
lastPromotedAt: written.length > 0 ? isoSecond(now) : (previous?.lastPromotedAt ?? null),
});
appendLessonsEvent(vault, BRAIN_LOG_EVENT_KIND.lessonsApproved, {
pref: renderPrefLink({ id: prefId }),
targets: targets.targets.join(", "),
approved_content_hash: liveHash,
consent,
agent,
});
if (written.length > 0) {
appendLessonsEvent(vault, BRAIN_LOG_EVENT_KIND.lessonsPromoted, {
targets: written.join(", "),
prefs: renderPrefLink({ id: prefId }),
agent,
});
}
// Name the cap's shortfall: a just-approved lesson that sorts past the
// `lessons.limit` cut stays approved and recorded, and the result says
// so by name instead of going quiet while the block omits it.
const limit = lessonsBlockLimit(vault);
const dropped: string[] = [];
for (const target of targets.targets) {
for (const id of canonicalRenderFor(sim.promotable, simulated, target, vault)?.droppedIds ??
[]) {
if (!dropped.includes(id)) dropped.push(id);
}
}
const droppedLines = dropped.map(
(id) =>
`capped: ${id} did not fit the lessons block (lessons.limit ${limit}); it stays ` +
"approved and rides the block when the limit widens or an earlier lesson drops",
);
if (json) {
okJson({
command: "brain lessons approve",
prefId,
consent,
recorded: true,
written: written.length > 0,
targets: targets.targets,
changed: written,
dropped,
});
} else {
ok(
`approved: ${prefId} (targets: ${targets.targets.join(", ")}; ` +
`${written.length > 0 ? `wrote ${written.join(", ")}` : "block already current"})` +
(droppedLines.length > 0 ? `\n${droppedLines.join("\n")}` : ""),
);
}
return LESSONS_EXIT.ok;
}
// ----- deny -------------------------------------------------------------------
async function lessonsDeny(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
apply: { type: "boolean" },
yes: { type: "boolean" },
json: { type: "boolean" },
});
const apply = flags["apply"] === true;
const yes = flags["yes"] === true;
const json = flags["json"] === true;
const rawId = positional[0]?.trim() ?? "";
if (rawId === "") {
return usageError("brain lessons deny requires a preference id: deny <pref-id>");
}
const { config, vault } = brainVerbContext(flags);
const agent = resolveBrainAgent(flags, config);
const prefId = rawId.startsWith("pref-") ? rawId : `pref-${rawId}`;
// A malformed promotion scopes value refuses the verb by name, before
// anything is recorded (see resolvePromotionScopesStrict).
let inputs: ReturnType<typeof gatherLessonsPromotionInputs>;
try {
inputs = gatherLessonsPromotionInputs(vault, { configPath: config });
} catch (err) {
return fail(rulesBlockErrorLine(err));
}
const pref = inputs.preferences.find((entry) => entry.id === prefId);
if (pref === undefined) {
process.stderr.write(
`error: no readable preference named ${prefId} under ${join(vault, "Brain", "preferences")}\n`,
);
return LESSONS_EXIT.usage;
}
const liveHash = computeContentHash(pref.principle, pref.scope);
if (!apply) {
const line =
`would record a denial for ${prefId} (no rules file is written; ` + "pass --apply to record)";
if (json) {
writeJson({
command: "brain lessons deny",
prefId,
apply: false,
written: false,
plan: line,
});
} else {
ok(line);
}
return LESSONS_EXIT.ok;
}
// Consent gates the ledger write: a denial is a state change the
// operator owns, so the same ladder sits above it.
if (!yes) {
if (json || !process.stdin.isTTY) {
return refuseHeadless(json, `denying ${prefId}`);
}
process.stderr.write(`Record the denial of ${prefId}? No rules file is written. [y/N] `);
const ans = await readSingleLine();
if (ans.trim().toLowerCase() !== "y" && ans.trim().toLowerCase() !== "yes") {
ok("denial cancelled; nothing was recorded");
return LESSONS_EXIT.ok;
}
}
const now = new Date();
const consent = consentVerdict(yes);
recordLessonApproval(vault, {
prefId,
decision: "denied",
decidedAt: isoSecond(now),
decidedBy: consent,
approvedContentHash: liveHash,
targets: [],
blockId: RULES_BLOCK_ID.lessons,
lastPromotedAt: null,
});
appendLessonsEvent(vault, BRAIN_LOG_EVENT_KIND.lessonsDenied, {
pref: renderPrefLink({ id: prefId }),
consent,
agent,
});
if (json) {
okJson({ command: "brain lessons deny", prefId, consent, recorded: true, targets: [] });
} else {
ok(`denied: ${prefId} (recorded; a managed block drops it on the next refresh-blocks run)`);
}
return LESSONS_EXIT.ok;
}
// ----- refresh-blocks -----------------------------------------------------------
async function lessonsRefreshBlocks(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
apply: { type: "boolean" },
yes: { type: "boolean" },
force: { type: "boolean" },
json: { type: "boolean" },
});
const apply = flags["apply"] === true;
const yes = flags["yes"] === true;
const force = flags["force"] === true;
const json = flags["json"] === true;
const { config, vault } = brainVerbContext(flags);
const agent = resolveBrainAgent(flags, config);
const ledger = readLessonApprovals(vault);
// A malformed promotion scopes value refuses the verb by name, before
// any plan or write (see resolvePromotionScopesStrict).
let split: Qualification;
try {
split = qualify(vault, config, ledger);
} catch (err) {
return fail(rulesBlockErrorLine(err));
}
const { promotable, blocked } = split;
const stale = blocked
.filter((entry) => entry.reason === LESSON_PROMOTION_BLOCKED.staleApproval)
.map((entry) => entry.prefId);
// Under management = an approved decision named the file AND the file
// carries the lessons pair. Discovery by existence over the fixed list,
// never glob; refresh never creates a block.
const universe = (AGENT_INSTRUCTION_FILES as ReadonlyArray<string>).filter((name) =>
ledger.some((row) => row.decision === "approved" && row.targets.includes(name)),
);
const skips: RefreshSkip[] = [];
const errors: string[] = [];
const actions: RefreshAction[] = [];
for (const target of universe) {
const file = join(vault, target);
if (!existsSync(file)) {
skips.push({ target, reason: "no such file at the vault root (refresh never creates it)" });
continue;
}
let extracted: string | null;
try {
extracted = readRulesBlock(file, RULES_BLOCK_ID.lessons);
} catch (err) {
errors.push(`${target}: ${rulesBlockErrorLine(err)}`);
continue;
}
if (extracted === null) {
skips.push({ target, reason: "no managed lessons block (refresh never creates one)" });
continue;
}
let render: RenderedLessonsBlock | null;
try {
render = canonicalRenderFor(promotable, ledger, target, vault);
} catch (err) {
// A canonical body that cannot render (a lesson whose scope could
// forge a marker line) is a named per-target error, not a crash.
errors.push(`${target}: ${rulesBlockErrorLine(err)}`);
continue;
}
const body = render === null ? null : render.body;
const installedAtMs = installedAtMsFor(ledger, target);
if (body === null) {
// Removal is the empty qualified set's only honest render. The
// writer carries no divergence gate on removal, so the same
// hand-edit slack guards it here: refuse unless --force.
if (touchedSincePromotion(installedAtMs, file) && !force) {
errors.push(
`${target}: ${RULES_BLOCK_ERROR_KIND.userModifiedBlock}: appears hand-edited since the ` +
"last promotion; refusing to remove the block. Re-run with --force to remove it anyway",
);
continue;
}
actions.push({ target, kind: "remove", body: "", installedAtMs, droppedIds: [] });
continue;
}
actions.push({
target,
kind: "write",
body,
installedAtMs,
droppedIds: render === null ? [] : render.droppedIds,
});
}
if (errors.length > 0) {
process.stderr.write(errors.map((line) => `error: ${line}`).join("\n") + "\n");
return LESSONS_EXIT.runtimeError;
}
const staleLines = stale.map(
(id) => `stale approval: ${id} - the approved text moved; approve again to re-pin it`,
);
// The cap's shortfall, named per target: a qualified lesson past the
// `lessons.limit` cut is reported, never silently truncated.
const droppedByTarget = actions
.filter((action) => action.kind === "write" && action.droppedIds.length > 0)
.map((action) => ({ target: action.target, ids: action.droppedIds }));
const dropLines = droppedByTarget.flatMap((entry) =>
entry.ids.map((id) => `capped: ${id} past the lessons.limit cut on ${entry.target}`),
);
if (actions.length === 0) {
const lines = [
"no lessons block under management - refresh never creates a block; approve a lesson first",
...skips.map((skip) => ` ${skip.target}: ${skip.reason}`),
...staleLines,
];
if (json) {
writeJson({
command: "brain lessons refresh-blocks",
apply,
changed: [],
removed: [],
skips,
stale,
dropped: [],
});
} else {
ok(lines.join("\n"));
}
return LESSONS_EXIT.ok;
}
// Dry pass first: it computes (and refuses) exactly like the real pass,
// so the operator sees the true plan and a refusal lands before any
// consent is asked. A writer refusal here is the verdict for the whole
// run - named by kind on stderr, nothing written, exit 1.
let dry: RefreshPassResult;
try {
dry = runRefreshPass(vault, actions, { dryRun: true, force });
} catch (err) {
process.stderr.write(`error: ${rulesBlockErrorLine(err)}\n`);
return LESSONS_EXIT.runtimeError;
}
const planLines = [
`refresh plan for ${actions.length} managed block(s)${apply ? "" : " (dry run; pass --apply to write)"}:`,
...dry.changed.map((target) => ` ${target}: would write the managed lessons block`),
...dry.unchanged.map((target) => ` ${target}: block already current (no change)`),
...dry.removed.map(
(target) => ` ${target}: would remove the block (no qualified lessons remain)`,
),
...dropLines.map((line) => ` ${line}`),
...skips.map((skip) => ` ${skip.target}: ${skip.reason}`),
...staleLines,
];
if (!apply) {
if (json) {
writeJson({
command: "brain lessons refresh-blocks",
apply: false,
wouldChange: dry.changed,
wouldRemove: dry.removed,
skips,
stale,
dropped: droppedByTarget,
});
} else {
ok(planLines.join("\n"));
}
return LESSONS_EXIT.ok;
}
// Consent above the write lane, the install ladder verbatim.
if (!yes) {
if (json || !process.stdin.isTTY) {
return refuseHeadless(json, "refreshing the managed lessons blocks");
}
process.stderr.write(planLines.join("\n") + "\n");
process.stderr.write("Proceed? [y/N] ");
const ans = await readSingleLine();
if (ans.trim().toLowerCase() !== "y" && ans.trim().toLowerCase() !== "yes") {
ok("refresh cancelled; nothing was written");
return LESSONS_EXIT.ok;
}
}
let real: RefreshPassResult;
try {
real = runRefreshPass(vault, actions, { dryRun: false, force });
} catch (err) {
process.stderr.write(`error: ${rulesBlockErrorLine(err)}\n`);
return LESSONS_EXIT.runtimeError;
}
// Stamp the rows whose content a write actually delivered, then append
// the promotion event. A removal stamps nothing: dropping a lesson is
// derived-state maintenance, not a delivery.
const now = new Date();
const stamped = new Set<string>();
for (const target of real.changed) {
for (const candidate of qualifiedForFile(promotable, ledger, target)) {
stamped.add(candidate.prefId);
}
}
for (const prefId of stamped) {
markLessonPromoted(vault, prefId, now);
}
if (real.changed.length > 0) {
appendLessonsEvent(vault, BRAIN_LOG_EVENT_KIND.lessonsPromoted, {
targets: real.changed.join(", "),
prefs: [...stamped].map((id) => renderPrefLink({ id })).join("\n"),
agent,
});
}
if (json) {
okJson({
command: "brain lessons refresh-blocks",
consent: consentVerdict(yes),
changed: real.changed,
removed: real.removed,
current: real.unchanged,
skips,
stale,
dropped: droppedByTarget,
stamped: [...stamped],
});
} else {
const lines = [
...real.changed.map((target) => `wrote: ${target}`),
...real.removed.map((target) => `removed the lessons block from: ${target}`),
...real.unchanged.map((target) => `already current: ${target}`),
...dropLines,
...skips.map((skip) => `skipped: ${skip.target} (${skip.reason})`),
...staleLines,
...(stamped.size > 0 ? [`stamped lastPromotedAt: ${[...stamped].join(", ")}`] : []),
];
ok(lines.join("\n"));
}
return LESSONS_EXIT.ok;
}
/** The outcome of one refresh pass, targets grouped by what happened. */
interface RefreshPassResult {
readonly changed: string[];
readonly unchanged: string[];
readonly removed: string[];
}
/** One pass over the planned actions, dry or real; refusals propagate. */
function runRefreshPass(
vault: string,
actions: ReadonlyArray<RefreshAction>,
opts: { readonly dryRun: boolean; readonly force: boolean },
): RefreshPassResult {
const changed: string[] = [];
const unchanged: string[] = [];
const removed: string[] = [];
for (const action of actions) {
const file = join(vault, action.target);
if (action.kind === "write") {
const result = writeBlock(file, action.body, {
dryRun: opts.dryRun,
force: opts.force,
installedAtMs: action.installedAtMs,
});
if (result.changed) changed.push(action.target);
else unchanged.push(action.target);
} else {
const result = removeRulesBlock(file, RULES_BLOCK_ID.lessons, { dryRun: opts.dryRun });
if (result.removed) removed.push(action.target);
else unchanged.push(action.target);
}
}
return { changed, unchanged, removed };
}