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
/**
* `Brain/lessons.md` — the unified, signed, recency-scored lessons
* digest (Outcome-tagged lessons loop, t_62363378).
*
* OSB already owns the two halves of a lessons corpus as separate
* registries:
*
* - NEGATIVE knowledge — `Brain/dead-ends/` ("avoid X"), and the
* `violated` / `outdated` apply-evidence rows against a preference;
* - POSITIVE knowledge — `Brain/preferences/` confirmed rules and the
* `applied` apply-evidence rows that corroborate them.
*
* This module folds both classes into ONE outcome-tagged corpus scored
* by a SIGNED, recency-decayed weight so that a fresh dead-end
* outweighs a stale "useful", and promotes a lesson to a corroborated
* tier only once ≥N distinct results back it — otherwise it stays
* tentative, and a rule with both positive and negative recent
* evidence renders as CONTESTED (the displayed stance follows the sign
* of the decayed score, so recency wins).
*
* It is NOT a parallel loop: the corpus is derived from the existing
* dead-end notes and apply-evidence log, the decay curve is the shared
* `decayWeight` from continuity's usage-signal, and the digest is
* regenerated at the tail of every `dream` pass exactly like
* `Brain/active.md`. The SessionStart / PostCompact hook injects it
* alongside `active.md`, so the agent gets a single auto-loaded lessons
* surface without querying dead-ends and preferences independently.
*
* Pure derivation: no LLM, no network, no clock-dependent content
* beyond the `generated_at` stamp. Identical inputs produce identical
* bodies; the write is idempotent and atomic (mirrors `active.ts`).
*/
import { legacyVaultOf } from "./no-vault.ts";
import { existsSync, mkdirSync, readdirSync } from "node:fs";
import { dirname } from "node:path";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import { parseFrontmatter } from "../vault.ts";
import { readGeneratedAt } from "./active.ts";
import { readerRefView, type ArtifactRefView } from "./artifact-ref-view.ts";
import { storeRecordRefView } from "./store-record-visibility.ts";
import { laneVaultRoot } from "../store/lane-pages.ts";
import { decayWeight } from "./continuity/usage-signal.ts";
import { listDeadEnds, type DeadEndEntry } from "./dead-ends.ts";
import { logEntryAtReach } from "./log-events-at-reach.ts";
import type { BrainLogEntry } from "./log.ts";
import { brainDirsForWrite, brainDirsOf, brainLessonsPath, vaultRelative } from "./paths.ts";
import { compiledDigestPath, digestsRenderedOnDemand } from "./compiled-digest-path.ts";
import { legacyMemoryPage, type MemoryPage, storeMemoryPages } from "./memory-pages.ts";
import { logDayReader, withLogReadPass } from "./log-days.ts";
import { parsePreferenceMeta } from "./preference.ts";
import {
LESSONS_CORROBORATION_MIN_DEFAULT,
LESSONS_HALF_LIFE_DAYS_DEFAULT,
LESSONS_LIMIT_DEFAULT,
loadBrainConfig,
} from "./policy.ts";
import { isoSecond } from "./time.ts";
import { normaliseWikilinkTarget } from "./wikilink.ts";
import {
BRAIN_APPLY_RESULT,
BRAIN_LOG_EVENT_KIND,
BRAIN_PREFERENCE_STATUS,
type BrainPreference,
} from "./types.ts";
const FRONTMATTER_KIND = "brain-lessons";
/**
* A net-positive lesson below the corroboration floor is `tentative`;
* once ≥N distinct results back it, `preferred`. A rule carrying BOTH
* positive and negative recent evidence is `contested` (recency-wins:
* the displayed stance follows the sign of the decayed score). A
* purely-negative node (a dead-end, or a rule only ever violated) is
* `avoid`.
*/
export const LESSON_TIER = {
preferred: "preferred",
tentative: "tentative",
contested: "contested",
avoid: "avoid",
} as const;
export type LessonTier = (typeof LESSON_TIER)[keyof typeof LESSON_TIER];
/** The stance a `contested` lesson currently leans toward. */
export const LESSON_STANCE = {
positive: "positive",
negative: "negative",
} as const;
export type LessonStance = (typeof LESSON_STANCE)[keyof typeof LESSON_STANCE];
export interface LessonEntry {
/** `pref-<slug>` or `de-<date>-<slug>`. */
readonly id: string;
readonly kind: "preference" | "dead-end";
/** Preference principle or dead-end approach. */
readonly title: string;
readonly scope: string | null;
readonly tier: LessonTier;
/** Positive decayed mass minus negative decayed mass, rounded to 4dp. */
readonly signedScore: number;
readonly positiveMass: number;
readonly negativeMass: number;
/** Distinct positive-outcome artifacts corroborating the lesson. */
readonly corroboration: number;
/** For `contested` lessons, the recency-decided leaning; else null. */
readonly stance: LessonStance | null;
/** ISO timestamp of the most recent contributing outcome, or null. */
readonly lastOutcomeAt: string | null;
}
export interface ComputeLessonsOptions {
/** Scoring anchor. Defaults to `new Date()`. */
readonly now?: Date;
/** Exponential half-life of the recency decay, in days. Default 30. */
readonly halfLifeDays?: number;
/** Distinct-result count required for the `preferred` tier. Default 2. */
readonly corroborationMin?: number;
/** Max lessons returned. Default 20. */
readonly limit?: number;
/**
* Whether an apply-evidence event may count. Omitted, every event the
* scoring reads counts.
*/
readonly keepEvent?: (entry: BrainLogEntry) => boolean;
}
/** Mutable per-node accumulator during the scoring pass. */
interface Accumulator {
positiveMass: number;
negativeMass: number;
readonly positiveArtifacts: Set<string>;
lastOutcomeMs: number;
}
const EPSILON = 1e-9;
/**
* Single-event recency weight from the shared continuity decay curve.
* Modelled as a record with zero access count and no last-access, so
* `decayWeight` reduces to the pure `0.5^(age/halfLife)` exponential
* (floored at its `minWeight`) — the same half-life OSB uses for
* working-memory continuity.
*/
function eventWeight(eventMs: number, nowMs: number, halfLifeDays: number): number {
return decayWeight({ createdAtMs: eventMs, accessCount: 0, lastAccessAtMs: null }, nowMs, {
halfLifeDays,
});
}
/**
* Fold the preference corpus and the dead-end corpus into one ranked,
* signed, recency-scored, corroboration-tiered lesson list.
*
* Pure read. The caller passes the candidate preferences (already
* filtered to `confirmed | quarantine`) and the active dead-ends;
* apply-evidence outcomes are harvested from `Brain/log/`.
*/
export function computeLessons(
vault: string | null,
preferences: ReadonlyArray<BrainPreference>,
deadEnds: ReadonlyArray<DeadEndEntry>,
opts: ComputeLessonsOptions = {},
): ReadonlyArray<LessonEntry> {
const now = opts.now ?? new Date();
const nowMs = now.getTime();
const halfLifeDays = opts.halfLifeDays ?? LESSONS_HALF_LIFE_DAYS_DEFAULT;
const corroborationMin = opts.corroborationMin ?? LESSONS_CORROBORATION_MIN_DEFAULT;
const limit = opts.limit ?? LESSONS_LIMIT_DEFAULT;
// Index the candidate preferences by their normalised id so an
// apply-evidence row spelled `[[pref-x|principle]]` resolves to one
// node. Retired rules are excluded upstream and never scored here.
const prefByKey = new Map<string, BrainPreference>();
for (const p of preferences) {
if (
p.status !== BRAIN_PREFERENCE_STATUS.confirmed &&
p.status !== BRAIN_PREFERENCE_STATUS.quarantine
) {
continue;
}
const key = normaliseWikilinkTarget(p.id);
if (key !== null) prefByKey.set(key, p);
}
const accByKey = new Map<string, Accumulator>();
const accFor = (key: string): Accumulator => {
let acc = accByKey.get(key);
if (acc === undefined) {
acc = { positiveMass: 0, negativeMass: 0, positiveArtifacts: new Set(), lastOutcomeMs: 0 };
accByKey.set(key, acc);
}
return acc;
};
// One pass over every log day, bucketing signed outcomes by pref.
if (prefByKey.size > 0) {
scoreApplyEvidence(vault, prefByKey, accFor, nowMs, halfLifeDays, opts.keepEvent);
}
const entries: LessonEntry[] = [];
// Preference-derived lessons.
for (const [key, pref] of prefByKey) {
const acc = accByKey.get(key);
if (acc === undefined) continue; // no outcome evidence → not a lesson yet
entries.push(
buildEntry({
id: pref.id,
kind: "preference",
title: pref.principle,
scope: pref.scope ?? null,
acc,
corroborationMin,
}),
);
}
// Dead-end lessons: one negative outcome stamped at creation. They
// are inherently `avoid` — a recorded failed approach.
for (const de of deadEnds) {
const createdMs = Date.parse(de.created_at);
if (Number.isNaN(createdMs)) continue;
const weight = eventWeight(createdMs, nowMs, halfLifeDays);
const acc: Accumulator = {
positiveMass: 0,
negativeMass: weight,
positiveArtifacts: new Set(),
lastOutcomeMs: createdMs,
};
entries.push(
buildEntry({
id: de.id,
kind: "dead-end",
title: de.approach,
scope: null,
acc,
corroborationMin,
}),
);
}
// Rank by salience — the dominant decayed mass — so the strongest
// signal (positive, negative, or contested) surfaces first. Ties
// break to the most recent outcome, then to a stable id order.
entries.sort((a, b) => {
const sa = Math.max(a.positiveMass, a.negativeMass);
const sb = Math.max(b.positiveMass, b.negativeMass);
if (sb !== sa) return sb - sa;
const ta = a.lastOutcomeAt ? Date.parse(a.lastOutcomeAt) : 0;
const tb = b.lastOutcomeAt ? Date.parse(b.lastOutcomeAt) : 0;
if (tb !== ta) return tb - ta;
return a.id.localeCompare(b.id);
});
return Object.freeze(entries.slice(0, limit).map((e) => Object.freeze(e)));
}
/** Walk the log once, accumulating signed apply-evidence per pref. */
function scoreApplyEvidence(
vault: string | null,
prefByKey: ReadonlyMap<string, BrainPreference>,
accFor: (key: string) => Accumulator,
nowMs: number,
halfLifeDays: number,
keepEvent: ((entry: BrainLogEntry) => boolean) | undefined,
): void {
const dirs = brainDirsOf(vault);
const log = logDayReader(vault);
if (!log.stored && !existsSync(dirs.log)) return;
for (const datePrefix of log.dates) {
let parsed;
try {
parsed = log.day(datePrefix);
} catch (err) {
process.stderr.write(
`warning: lessons: failed to read ${datePrefix}: ${(err as Error).message}\n`,
);
continue;
}
for (const e of parsed.entries) {
if (e.eventType !== BRAIN_LOG_EVENT_KIND.applyEvidence) continue;
if (keepEvent !== undefined && !keepEvent(e)) continue;
const prefField = e.body["preference"];
if (typeof prefField !== "string") continue;
const key = normaliseWikilinkTarget(prefField);
if (key === null) continue;
const pref = prefByKey.get(key);
if (pref === undefined) continue;
// Never harvest rows that predate the pref's existence — that would
// be a different rule under a reused slug history.
if (e.timestamp < pref.created_at) continue;
const eventMs = Date.parse(e.timestamp);
if (Number.isNaN(eventMs)) continue;
const result = e.body["result"];
if (typeof result !== "string") continue;
const weight = eventWeight(eventMs, nowMs, halfLifeDays);
const acc = accFor(key);
acc.lastOutcomeMs = Math.max(acc.lastOutcomeMs, eventMs);
if (result === BRAIN_APPLY_RESULT.applied) {
acc.positiveMass += weight;
const artifact = e.body["artifact"];
if (typeof artifact === "string" && artifact.trim().length > 0) {
acc.positiveArtifacts.add(normaliseWikilinkTarget(artifact) ?? artifact.trim());
}
} else if (result === BRAIN_APPLY_RESULT.violated || result === BRAIN_APPLY_RESULT.outdated) {
acc.negativeMass += weight;
}
}
}
}
interface BuildEntryInput {
readonly id: string;
readonly kind: "preference" | "dead-end";
readonly title: string;
readonly scope: string | null;
readonly acc: Accumulator;
readonly corroborationMin: number;
}
function buildEntry(input: BuildEntryInput): LessonEntry {
const { acc } = input;
const signed = acc.positiveMass - acc.negativeMass;
const corroboration = acc.positiveArtifacts.size;
let tier: LessonTier;
let stance: LessonStance | null = null;
if (acc.positiveMass > EPSILON && acc.negativeMass > EPSILON) {
tier = LESSON_TIER.contested;
// Recency-wins: the decayed sum already leans toward whichever
// outcome class is fresher / stronger. Treat a dead-even score as
// negative — an unresolved conflict is not an endorsement.
stance = signed > EPSILON ? LESSON_STANCE.positive : LESSON_STANCE.negative;
} else if (signed > EPSILON) {
tier = corroboration >= input.corroborationMin ? LESSON_TIER.preferred : LESSON_TIER.tentative;
} else {
tier = LESSON_TIER.avoid;
}
return {
id: input.id,
kind: input.kind,
title: input.title,
scope: input.scope,
tier,
signedScore: round4(signed),
positiveMass: round4(acc.positiveMass),
negativeMass: round4(acc.negativeMass),
corroboration,
stance,
lastOutcomeAt: acc.lastOutcomeMs > 0 ? new Date(acc.lastOutcomeMs).toISOString() : null,
};
}
function round4(n: number): number {
return Math.round(n * 10000) / 10000;
}
// ----- Regeneration (mirrors active.ts) ------------------------------------
export interface RegenerateLessonsOptions {
/** Wall clock for `generated_at`. Defaults to `new Date()`. */
readonly now?: Date;
}
export interface RegenerateLessonsResult {
readonly path: string;
readonly changed: boolean;
readonly counts: LessonCounts;
}
export interface LessonCounts {
readonly preferred: number;
readonly tentative: number;
readonly contested: number;
readonly avoid: number;
readonly total: number;
}
/** Who is reading the shared lessons digest. */
export interface LessonsReaderOptions {
/**
* May this reader see the record at a vault-relative path? A preference
* or dead-end it answers `false` for is treated as absent, and so is
* every apply-evidence event naming a page it cannot see. Omitted,
* nothing is filtered. It never reaches the shared write.
*/
readonly readable?: (rel: string) => boolean;
/**
* The reader is below local reach: apply-evidence events of the store's
* `private` partition are not counted for it.
*/
readonly withholdsPrivate?: boolean;
}
interface RenderLessonsOptions extends LessonsReaderOptions {
readonly now: Date;
readonly generatedAt: string;
}
/** A rendered lessons digest that has NOT been written anywhere. */
export interface LessonsRender {
/** Body only, no frontmatter: what the idempotency check compares. */
readonly body: string;
/** Frontmatter + body: exactly the bytes a write would store. */
readonly document: string;
readonly counts: LessonCounts;
}
function renderLessons(vault: string | null, opts: RenderLessonsOptions): LessonsRender {
// With no vault every memory path is vault-relative already, and the
// events are judged against the store's records (design D14): a reader
// with a scope never scores an event it could not see.
const withholdsPrivate = opts.withholdsPrivate === true;
let refs: ArtifactRefView | null = null;
if (vault !== null) refs = readerRefView(vault, opts.readable, withholdsPrivate);
else if (opts.readable !== undefined || withholdsPrivate) {
const readable = opts.readable ?? (() => true);
const view = storeRecordRefView((page) => readable(page.rel));
refs = withholdsPrivate ? Object.freeze({ ...view, withholdsPrivate: true }) : view;
}
const visible = (path: string): boolean =>
vault === null || refs === null
? (opts.readable?.(path) ?? true)
: refs.visible(vaultRelative(path, vault));
const preferences = readActivePreferences(vault).filter(({ path }) => visible(path));
// The dead-end lane works in every mode: with no vault it lives under
// its stand-in root, and its paths are judged relative to that root.
const deadEndRoot = laneVaultRoot(vault);
const deadEnds = listDeadEnds(deadEndRoot).entries.filter((de) =>
vault === null
? (opts.readable?.(vaultRelative(de.path, deadEndRoot)) ?? true)
: visible(de.path),
);
// Tunables from `_brain.yaml:lessons.*`. A malformed config never
// blocks the digest — fall back to the defaults (doctor's job).
let halfLifeDays = LESSONS_HALF_LIFE_DAYS_DEFAULT;
let corroborationMin = LESSONS_CORROBORATION_MIN_DEFAULT;
let limit = LESSONS_LIMIT_DEFAULT;
try {
const cfg = loadBrainConfig(vault);
if (cfg.lessons) {
halfLifeDays = cfg.lessons.half_life_days ?? halfLifeDays;
corroborationMin = cfg.lessons.corroboration_min ?? corroborationMin;
limit = cfg.lessons.limit ?? limit;
}
} catch {
// intentional fallback — config error is doctor's job to surface
}
const lessons = computeLessons(
vault,
preferences.map(({ pref }) => pref),
deadEnds,
{
now: opts.now,
halfLifeDays,
corroborationMin,
limit,
...(refs === null || refs.filtersNothing
? {}
: { keepEvent: (e: BrainLogEntry) => logEntryAtReach(refs, e) !== null }),
},
);
const body = renderBody(lessons, { corroborationMin, halfLifeDays });
return {
body,
document: renderDocument(body, opts.generatedAt),
counts: {
preferred: lessons.filter((l) => l.tier === LESSON_TIER.preferred).length,
tentative: lessons.filter((l) => l.tier === LESSON_TIER.tentative).length,
contested: lessons.filter((l) => l.tier === LESSON_TIER.contested).length,
avoid: lessons.filter((l) => l.tier === LESSON_TIER.avoid).length,
total: lessons.length,
},
};
}
/**
* Regenerate `<vault>/Brain/lessons.md`. Idempotent: the rendered body
* is compared byte-for-byte against the existing file before writing so
* a no-op `dream` rerun leaves the file (and its mtime) untouched.
*
* Parser failures on individual preference / dead-end files are
* swallowed and the offending file is omitted, exactly like
* `regenerateActive` — a single corrupted frontmatter must not blank
* the whole lessons view. `brain_doctor` is the surface for corruption.
*
* The write is ALWAYS unscoped: a reader's narrowing is
* {@link renderLessonsForReader}, which writes nothing.
*/
export function regenerateLessons(
vault: string | null,
opts: RegenerateLessonsOptions = {},
): RegenerateLessonsResult {
const now = opts.now ?? new Date();
const path = compiledDigestPath(vault, "lessons");
const rendered = renderLessons(vault, { now, generatedAt: isoSecond(now) });
const existingBody = readExistingBody(path);
const changed = existingBody === null || existingBody !== rendered.body.trim();
if (changed) {
// The device-local cache directory of a store-only machine may not exist yet.
if (digestsRenderedOnDemand(vault)) mkdirSync(dirname(path), { recursive: true });
atomicWriteFileSync(path, rendered.document);
}
return { path, changed, counts: rendered.counts };
}
/**
* The lessons digest as ONE reader may see it, rendered in memory and
* scored at the `generated_at` instant already on disk, so the narrowed
* document names and scores the same generation the shared file does.
* Nothing is written. The file must exist; the caller regenerates it
* first.
*/
export function renderLessonsForReader(
vault: string | null,
opts: LessonsReaderOptions,
): LessonsRender {
const generatedAt = readGeneratedAt(compiledDigestPath(vault, "lessons"));
const stampMs = generatedAt === null ? Number.NaN : Date.parse(generatedAt);
const now = Number.isNaN(stampMs) ? new Date() : new Date(stampMs);
return renderLessons(vault, {
...opts,
now,
generatedAt: generatedAt ?? isoSecond(now),
});
}
/**
* The file a reader of the shared lessons digest reads:
* `Brain/lessons.md` on an unswitched machine, as it is; on a store-only
* machine the device-local cache, rendered first (D14 item 7).
*/
export function lessonsDigestPathForRead(
vault: string | null,
opts: RegenerateLessonsOptions = {},
): string {
if (vault !== null && !digestsRenderedOnDemand(vault)) return brainLessonsPath(vault);
// The cached generation stands while a render at its own instant still
// gives its body (see `activeDigestPathForRead`).
const path = compiledDigestPath(vault, "lessons");
const stamp = readGeneratedAt(path);
const stampMs = stamp === null ? Number.NaN : Date.parse(stamp);
// One read pass: the check render and a regeneration share one log read.
return withLogReadPass(() => {
if (stamp !== null && !Number.isNaN(stampMs)) {
const atStamp = renderLessons(vault, { now: new Date(stampMs), generatedAt: stamp });
if (readExistingBody(path) === atStamp.body.trim()) return path;
}
return regenerateLessons(vault, opts).path;
});
}
/**
* Fire-and-warn wrapper around {@link regenerateLessons}, matching
* `regenerateActiveQuiet`. The lessons digest is a derived view: a
* failed write (disk full, permissions) must not mask the success of
* the `dream` pass that triggered it. The next pass retries.
*/
export function regenerateLessonsQuiet(
vault: string | null,
opts: RegenerateLessonsOptions = {},
): void {
try {
regenerateLessons(vault, opts);
} catch (err) {
process.stderr.write(`warning: regenerate lessons.md failed: ${(err as Error).message}\n`);
}
}
// ----- Scan helpers --------------------------------------------------------
interface PreferenceAtPath {
readonly pref: BrainPreference;
readonly path: string;
}
function legacyPreferencesPages(vault: string | null): MemoryPage[] {
const root = legacyVaultOf(vault, "readActivePreferences");
const dir = brainDirsForWrite(root).preferences;
if (!existsSync(dir)) return [];
return readdirSync(dir).map((name) => legacyMemoryPage(root, "preferences", name));
}
function readActivePreferences(vault: string | null): PreferenceAtPath[] {
// Reached from the shared write and from the per-reader render; both
// read the directory the write resolves, so they score the same set.
// Store pages on a store-only machine; only an unswitched machine
// resolves (and guards) the legacy folder, so a read never trips the
// write guard (frozen vault, migration in progress) for a folder it
// does not read.
const pages = storeMemoryPages(vault, "preferences") ?? legacyPreferencesPages(vault);
const out: PreferenceAtPath[] = [];
for (const page of pages) {
if (!page.name.endsWith(".md")) continue;
const path = page.path;
try {
out.push({ pref: parsePreferenceMeta(page.read()[0], path), path });
} catch {
// Corrupted / status-folder-mismatched — omit; doctor flags it.
}
}
return out;
}
// ----- Render helpers ------------------------------------------------------
interface RenderMeta {
readonly corroborationMin: number;
readonly halfLifeDays: number;
}
function renderBody(lessons: ReadonlyArray<LessonEntry>, meta: RenderMeta): string {
const out: string[] = [];
out.push("# Lessons");
out.push("");
out.push("Auto-generated by `dream`. Do not edit — changes will be overwritten.");
out.push("");
out.push(
`Signed, recency-decayed outcome corpus (half-life ${meta.halfLifeDays}d). ` +
`A rule reaches **preferred** once ≥${meta.corroborationMin} distinct results corroborate it.`,
);
out.push("");
if (lessons.length === 0) {
out.push("_No lessons yet — record apply-evidence outcomes and dead-ends to seed the corpus._");
while (out.length > 0 && out[out.length - 1] === "") out.pop();
return out.join("\n") + "\n";
}
const sections: ReadonlyArray<{ tier: LessonTier; heading: string; blurb: string }> = [
{
tier: LESSON_TIER.preferred,
heading: "Preferred",
blurb: "Net-positive and corroborated by enough distinct results.",
},
{
tier: LESSON_TIER.tentative,
heading: "Tentative",
blurb: "Net-positive but not yet corroborated by enough distinct results.",
},
{
tier: LESSON_TIER.contested,
heading: "Contested",
blurb: "Mixed recent evidence — the stance shown is the one recency currently favours.",
},
{
tier: LESSON_TIER.avoid,
heading: "Avoid",
blurb: "Dead-ends and rules whose recent evidence is net-negative.",
},
];
for (const section of sections) {
const group = lessons.filter((l) => l.tier === section.tier);
if (group.length === 0) continue;
out.push(`## ${section.heading} (${group.length})`);
out.push("");
out.push(`_${section.blurb}_`);
out.push("");
for (const l of group) out.push(renderLine(l));
out.push("");
}
while (out.length > 0 && out[out.length - 1] === "") out.pop();
return out.join("\n") + "\n";
}
function renderLine(l: LessonEntry): string {
const tags: string[] = [];
if (l.scope) tags.push(`scope: ${l.scope}`);
tags.push(`score: ${formatSigned(l.signedScore)}`);
if (l.tier === LESSON_TIER.preferred || l.tier === LESSON_TIER.tentative) {
tags.push(`corroboration: ${l.corroboration}`);
}
if (l.tier === LESSON_TIER.contested && l.stance) {
tags.push(`leaning: ${l.stance}`);
}
return `- \`${l.id}\` (${tags.join(", ")}) — ${l.title}`;
}
function formatSigned(n: number): string {
const fixed = n.toFixed(2);
return n > 0 ? `+${fixed}` : fixed;
}
function renderDocument(body: string, generatedAt: string): string {
return [
"---",
`kind: ${FRONTMATTER_KIND}`,
`generated_at: ${generatedAt}`,
"---",
"",
body.trimEnd(),
"",
].join("\n");
}
function readExistingBody(path: string): string | null {
if (!existsSync(path)) return null;
try {
const [, body] = parseFrontmatter(path);
return body;
} catch {
return null;
}
}