@codewithjuber/forgekit 0.8.0

package/src/ledger_store.js

@@ -0,0 +1,360 @@
+// forge ledger storage — the on-disk PCM ledger (docs/plans/substrate-v2/02-team-memory.md):
+// one immutable canonical-JSON file per claim (sharded by id prefix, bytes = pure
+// content so every replica writes the identical file), plus three append-only logs per
+// claim — evidence, provenance, tombstones — that git union-merges without conflicts
+// (`forge init` emits the .gitattributes rule). Everything author- or time-varying is
+// a log line; nothing on disk is ever edited in place.
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import {
+  authorTrust,
+  canonicalize,
+  claimId,
+  DORMANT_VAL,
+  emptyState,
+  liveClaims,
+  mergeStates,
+  mintClaim,
+  ORACLES,
+  SECRET_RE,
+  sealRecord,
+  sortRecords,
+  val,
+  validOutcome,
+} from "./ledger.js";
+
+/** The canonical repo ledger. (recall's global store keeps its own sibling ledger.) */
+export const repoLedger = (root = process.cwd()) => join(root, ".forge", "ledger");
+
+/** The union-merge rule consumer repos need for conflict-free ledger merges —
+ *  emitted into .gitattributes by `forge init` (see init.js). NOTE: .gitattributes
+ *  supports full-line comments only, so the rule ships with a comment line above it. */
+export const GITATTRIBUTES_RULE = [
+  "# PCM ledger logs are hash-deduped append-only sets - union merge is conflict-free (forge)",
+  ".forge/ledger/*/*.log merge=union",
+].join("\n");
+
+const LOGS = ["evidence", "provenance", "tombstones"];
+const claimPath = (dir, id) => join(dir, "claims", id.slice(0, 2), `${id}.json`);
+const logPath = (dir, log, id) => join(dir, log, `${id}.log`);
+
+/** Claim file bytes: pure content only. Identical for the same id on every replica. */
+const claimBytes = (claim) =>
+  `${canonicalize({ body: claim.body, kind: claim.kind, scope: claim.scope ?? {}, v: claim.v ?? 1 })}\n`;
+
+const readJson = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null; // one corrupt file must never take down the whole ledger
+  }
+};
+
+/** Parse an append-only log: one canonical-JSON record per line, deduped by content
+ *  hash, corrupt lines skipped. The single reader every log goes through. */
+function readLog(dir, log, id) {
+  const path = logPath(dir, log, id);
+  if (!existsSync(path)) return [];
+  const records = [];
+  for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch {}
+  }
+  // sortRecords, not file order: after a git union merge the two replicas' logs hold
+  // the same set in different line orders — views must not depend on that.
+  return sortRecords(records);
+}
+
+/** Append one sealed record to a log iff its hash isn't already present. */
+function appendRecord(dir, log, id, record) {
+  if (!record?.h) return { ok: false, reason: "record missing content hash" };
+  if (!existsSync(claimPath(dir, id)))
+    return { ok: false, reason: `no such claim in ledger: ${id}` };
+  if (readLog(dir, log, id).some((e) => e.h === record.h)) return { ok: true, deduped: true };
+  mkdirSync(join(dir, log), { recursive: true });
+  appendFileSync(logPath(dir, log, id), `${canonicalize(record)}\n`);
+  return { ok: true, deduped: false };
+}
+
+/** Walk every claim file: yields {id, path, raw, claim(valid-or-null)}. Shared by
+ *  loadState (keep valid) and verify (report invalid) so the two can never drift. */
+function* walkClaimFiles(dir) {
+  const claimsRoot = join(dir, "claims");
+  if (!existsSync(claimsRoot)) return;
+  for (const shard of readdirSync(claimsRoot).sort()) {
+    for (const f of readdirSync(join(claimsRoot, shard))
+      .filter((f) => f.endsWith(".json"))
+      .sort()) {
+      const path = join(claimsRoot, shard, f);
+      const id = f.replace(/\.json$/, "");
+      const parsed = readJson(path);
+      // Verify the address: a tampered/corrupt claim is surfaced as claim:null.
+      const valid = parsed && claimId(parsed.kind, parsed.body, parsed.scope) === id;
+      yield { id, path, raw: readFileSync(path, "utf8"), claim: valid ? { ...parsed, id } : null };
+    }
+  }
+}
+
+/**
+ * Persist a claim (idempotent — content-addressed). Bytes contain content only;
+ * the claim's provenance record (if any) is appended to the provenance log. A
+ * corrupt/truncated file at the claim's path is REPAIRED by rewriting the canonical
+ * bytes — a killed process must never leave a claim permanently unloadable.
+ * @returns {{ok:boolean, reason?:string, id?:string, existed?:boolean}}
+ */
+export function putClaim(dir, claim) {
+  if (!claim?.id || claim.id !== claimId(claim.kind, claim.body, claim.scope))
+    return { ok: false, reason: "claim id does not match canonical content hash" };
+  const text = claimBytes(claim);
+  if (SECRET_RE.test(text))
+    return { ok: false, reason: "refused: claim looks like it contains a secret/credential" };
+  const path = claimPath(dir, claim.id);
+  const already = existsSync(path);
+  const healthy = already && readJson(path) !== null && readFileSync(path, "utf8") === text;
+  if (!healthy) {
+    mkdirSync(join(dir, "claims", claim.id.slice(0, 2)), { recursive: true });
+    writeFileSync(path, text);
+  }
+  if (claim.provenance?.h) appendRecord(dir, "provenance", claim.id, claim.provenance);
+  return { ok: true, id: claim.id, existed: already && healthy };
+}
+
+/** Append one evidence outcome (deduped by its content hash — append is idempotent). */
+export function appendEvidence(dir, id, outcome) {
+  if (!validOutcome(outcome)) return { ok: false, reason: "invalid outcome (use outcomeRecord)" };
+  return appendRecord(dir, "evidence", id, outcome);
+}
+
+/** All evidence outcomes for a claim (corrupt lines skipped, duplicates dropped). */
+export function readEvidence(dir, id) {
+  return readLog(dir, "evidence", id);
+}
+
+/** Retract a claim — an append-only record, so two teammates retracting concurrently
+ *  both survive the merge (the view shows the earliest deterministically). */
+export function tombstone(dir, id, { author = "", reason = "", t = 0 } = {}) {
+  return appendRecord(dir, "tombstones", id, sealRecord({ author, reason, t }));
+}
+
+/**
+ * Ratify a claim — the fahm→ḥikma promotion (08-dashboard-ux.md §2): mint a `decision`
+ * claim pointing at the ratified claim's full id. Promotion is HUMAN-ONLY by design:
+ * the caller supplies the author (a person's identity, via gitAuthor()); nothing in the
+ * substrate ever calls this automatically. Append-only and content-addressed, so
+ * ratifying the same claim twice converges on the same decision ({existed:true}).
+ * @param {string} dir
+ * @param {string} idPrefix
+ * @param {{author?: string, t?: number}} [opts]
+ * @returns {{ok:boolean, reason?:string, decisionId?:string, ratifies?:string, existed?:boolean}}
+ */
+export function ratify(dir, idPrefix, { author = "", t = 0 } = {}) {
+  const target = getClaimByPrefix(dir, idPrefix);
+  if (!target) return { ok: false, reason: `no claim matching ${idPrefix}` };
+  const minted = mintClaim({
+    kind: "decision",
+    body: { ratifies: target.id, note: "" },
+    provenance: { agent: "dash", author },
+    t,
+  });
+  if (!minted.ok) return { ok: false, reason: "reason" in minted ? minted.reason : "mint failed" };
+  const put = putClaim(dir, minted.claim);
+  if (!put.ok) return { ok: false, reason: put.reason ?? "could not persist the decision claim" };
+  return { ok: true, decisionId: minted.claim.id, ratifies: target.id, existed: put.existed };
+}
+
+/** Load the full ledger state {claims, evidence, provenance, tombstones}. */
+export function loadState(dir) {
+  const state = emptyState();
+  for (const { id, claim } of walkClaimFiles(dir)) {
+    if (!claim) continue;
+    state.claims[id] = claim;
+    for (const log of LOGS) state[log][id] = readLog(dir, log, id);
+  }
+  return state;
+}
+
+/** All claims with evidence/provenance/tombstone views attached (retrieval input). */
+export function loadClaims(dir) {
+  return liveClaims(loadState(dir));
+}
+
+/** Find one claim by id prefix without scanning the whole ledger (ids are sharded by
+ *  their first two hex chars, so any prefix ≥ 2 chars pins the shard). */
+export function getClaimByPrefix(dir, prefix) {
+  if (!prefix || prefix.length < 2) return null;
+  const shardDir = join(dir, "claims", prefix.slice(0, 2));
+  if (!existsSync(shardDir)) return null;
+  const f = readdirSync(shardDir)
+    .filter((f) => f.endsWith(".json") && f.startsWith(prefix))
+    .sort()[0];
+  if (!f) return null;
+  const id = f.replace(/\.json$/, "");
+  const claim = readJson(join(shardDir, f));
+  if (!claim || claimId(claim.kind, claim.body, claim.scope) !== id) return null;
+  const state = emptyState();
+  state.claims[id] = { ...claim, id };
+  for (const log of LOGS) state[log][id] = readLog(dir, log, id);
+  return liveClaims(state)[0];
+}
+
+/** `forge ledger merge <path>` — semilattice merge of another on-disk ledger into
+ *  this one. Idempotent and order-independent by the CRDT property, so merging a
+ *  teammate's checkout, a backup, or a branch worktree is always safe. */
+export function mergeDirs(dstDir, srcDir) {
+  return importState(dstDir, loadState(srcDir));
+}
+
+/**
+ * `forge ledger blame <id-prefix>` — the full accountability view of one claim: who
+ * minted it (every author, via the provenance log), every evidence record in (t, h)
+ * order, retractions, and the per-author trust the ledger has earned (17:36's audit
+ * trail: every channel the agent used can be questioned).
+ */
+export function blame(dir, prefix, nowDay = 0) {
+  const claim = getClaimByPrefix(dir, prefix);
+  if (!claim) return null;
+  const trust = authorTrust(loadClaims(dir));
+  return {
+    id: claim.id,
+    kind: claim.kind,
+    body: claim.body,
+    scope: claim.scope,
+    minted: claim.provenanceAll,
+    evidence: claim.evidence,
+    tombstones: readLog(dir, "tombstones", claim.id),
+    val: val(claim, nowDay),
+    valTrustWeighted: val(claim, nowDay, { trust }),
+    trust: Object.fromEntries(
+      [
+        ...new Set(
+          [...claim.provenanceAll, ...claim.evidence].map((r) => r.author).filter(Boolean),
+        ),
+      ].map((a) => [a, trust[a] ?? 1]),
+    ),
+  };
+}
+
+/** Semilattice import: merge another ledger state into this directory (the mergeDirs
+ *  core). Idempotent; safe to re-run. */
+export function importState(dir, other) {
+  const merged = mergeStates(loadState(dir), other);
+  let claims = 0;
+  let records = 0;
+  for (const c of Object.values(merged.claims)) {
+    const r = putClaim(dir, c);
+    if (r.ok && !r.existed) claims++;
+    for (const log of LOGS) {
+      for (const rec of merged[log][c.id] ?? []) {
+        const a = appendRecord(dir, log, c.id, rec);
+        if (a.ok && !a.deduped) records++;
+      }
+    }
+  }
+  reindex(dir);
+  return { claims, records };
+}
+
+/** Regenerate LEDGER.md — the human index (like recall's MEMORY.md). */
+export function reindex(dir, nowDay = 0) {
+  const rows = loadClaims(dir)
+    .filter((c) => !c.tombstone)
+    .map((c) => `- \`${c.id.slice(0, 12)}\` ${c.kind} · val ${val(c, nowDay).toFixed(2)}`);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "LEDGER.md"),
+    ["# Proof-Carrying Memory ledger", "", ...rows, ""].join("\n"),
+  );
+  return rows.length;
+}
+
+/**
+ * Normal-form check (CI-friendly): every claim parses and matches its address; every
+ * log line parses, carries a TRUE content hash, and (for evidence) names a known
+ * oracle with the table weight; no secrets anywhere. Everything loadState silently
+ * skips, verify names.
+ * @returns {{ok:boolean, claims:number, outcomes:number, issues:string[]}}
+ */
+export function verify(dir) {
+  const issues = [];
+  let claims = 0;
+  let outcomes = 0;
+  const ids = [];
+  for (const { id, raw, claim } of walkClaimFiles(dir)) {
+    if (!claim) issues.push(`claim ${id}: unparseable or id mismatch`);
+    else {
+      claims++;
+      ids.push(id);
+    }
+    if (SECRET_RE.test(raw)) issues.push(`claim ${id}: contains secret-like content`);
+  }
+  for (const log of LOGS) {
+    const logRoot = join(dir, log);
+    if (!existsSync(logRoot)) continue;
+    for (const f of readdirSync(logRoot).filter((f) => f.endsWith(".log"))) {
+      const id = f.replace(/\.log$/, "");
+      for (const [n, line] of readFileSync(join(logRoot, f), "utf8").split(/\r?\n/).entries()) {
+        if (!line.trim()) continue;
+        const where = `${log} ${id}:${n + 1}`;
+        let o = null;
+        try {
+          o = JSON.parse(line);
+        } catch {}
+        if (!o?.h) {
+          issues.push(`${where}: unparseable or missing hash`);
+          continue;
+        }
+        const { h, ...rest } = o;
+        if (sealRecord(rest).h !== h) {
+          issues.push(`${where}: content hash mismatch (forged/corrupt)`);
+        } else if (log === "evidence") {
+          if (!validOutcome(o)) issues.push(`${where}: invalid outcome (oracle/result/ref)`);
+          else if (o.w !== ORACLES[o.oracle].w)
+            issues.push(`${where}: recorded weight ${o.w} != oracle table ${ORACLES[o.oracle].w}`);
+          else outcomes++;
+        }
+        if (SECRET_RE.test(line)) issues.push(`${where}: secret-like content`);
+      }
+    }
+  }
+  return { ok: issues.length === 0, claims, outcomes, issues };
+}
+
+/** Move dormant/tombstoned claim files to the attic (audit trail, never retrieved). */
+export function pruneToAttic(dir, id) {
+  const from = claimPath(dir, id);
+  if (!existsSync(from)) return { ok: false, reason: "no such claim" };
+  mkdirSync(join(dir, "attic"), { recursive: true });
+  renameSync(from, join(dir, "attic", `${id}.json`));
+  return { ok: true };
+}
+
+/** Counts + val distribution for `forge ledger stats` and the dashboard. Buckets use
+ *  the protocol's DORMANT_VAL threshold (and its mirror) — never a local literal. */
+export function stats(dir, nowDay = 0) {
+  const claims = loadClaims(dir);
+  const byKind = {};
+  const buckets = { dormant: 0, uncertain: 0, trusted: 0 };
+  for (const c of claims) {
+    byKind[c.kind] = (byKind[c.kind] ?? 0) + 1;
+    const v = val(c, nowDay);
+    if (v < DORMANT_VAL) buckets.dormant++;
+    else if (v < 1 - DORMANT_VAL) buckets.uncertain++;
+    else buckets.trusted++;
+  }
+  return {
+    total: claims.length,
+    tombstoned: claims.filter((c) => c.tombstone).length,
+    byKind,
+    val: buckets,
+  };
+}

package/src/lessons.js

@@ -0,0 +1,185 @@
+// forge lessons — the self-correcting core. PURE logic only (no fs/hooks here, so it's
+// fully unit-testable): a mistake scorer that won't fire on normal iteration, a
+// confidence lifecycle that lets wrong lessons die faster than right ones grow, and an
+// injection selector that never overflows a tool's context cap.
+//
+// Design invariants (why this isn't just Reflexion):
+//  - A lesson is trusted because it keeps being RE-CONFIRMED against fresh outcomes,
+//    never because it exists. Injection is NOT confirmation — only the storage/hook
+//    layer feeds independent outcome signals in here, never the act of injecting.
+//  - A mistake is defined by a BAD OUTCOME, not by "differs from a lesson", so a
+//    developer changing their mind retires a lesson instead of fighting it.
+
+/** Signal taxonomy: weight = prior that a real mistake occurred; family gates false positives. */
+// `solo: true` = trustworthy enough to fire a lesson on its own (only an explicit human
+// undo qualifies). Everything else needs a second signal from a different family — this is
+// what stops a stray "no problem" (S5) or a lone thrash (S3) from minting a false lesson.
+export const SIGNALS = {
+  S1: { weight: 0.45, family: "outcome" }, // test-fail then pass on same files
+  S2: { weight: 0.25, family: "behavioral" }, // agent edits code it just wrote
+  S3: { weight: 0.3, family: "behavioral" }, // repeated edits to same symbol
+  S4: { weight: 0.4, family: "outcome" }, // file/hunk reverted
+  S5: { weight: 0.35, family: "human" }, // user negative utterance (weak, noisy — never solo)
+  S6: { weight: 0.5, family: "human", solo: true }, // explicit undo (git revert/checkout) — trusted solo
+  S7: { weight: 0.35, family: "outcome" }, // lint/type/build regression introduced
+};
+
+// One source of truth for scope weighting — the PCM ledger core owns it now, so the
+// legacy injection path and Eq.-3 retrieval can never rank the same memory with
+// silently different weights during the bridge window.
+import { SCOPE_WEIGHT } from "./ledger.js";
+
+export { SCOPE_WEIGHT };
+
+/**
+ * Score whether a cluster of signals reflects a real mistake.
+ * noisy-OR (bounded in [0,1)) so three weak signals can't fake one strong one; a
+ * cross-family gate so a lone behavioral signal (thrash) never fires a lesson.
+ * @param {{signal:string, anti?:number}[]} events - anti in [0,1] scales a signal down.
+ * @returns {{p:number, fires:boolean, families:string[]}}
+ */
+export function scoreMistake(events) {
+  const valid = events.filter((e) => SIGNALS[e.signal]);
+  const product = valid.reduce((acc, e) => {
+    const w = SIGNALS[e.signal].weight * (e.anti ?? 1);
+    return acc * (1 - w);
+  }, 1);
+  const p = 1 - product;
+  const families = [...new Set(valid.map((e) => SIGNALS[e.signal].family))];
+  const soloOk = valid.some((e) => SIGNALS[e.signal].solo);
+  const fires = families.length >= 2 || soloOk;
+  return { p, fires, families };
+}
+
+/** Route a scored cluster: distill a lesson now, accumulate for later, or discard as variation. */
+export function classify(events) {
+  const { p, fires } = scoreMistake(events);
+  if (fires && p >= 0.7) return "distill";
+  if (p >= 0.4) return "accumulate";
+  return "discard";
+}
+
+/** A fresh lesson candidate. confidence starts at 0.5 (evidence 0, contradiction 0 → α=β=1). */
+export function newLesson(fields, nowDay = 0) {
+  return {
+    id: fields.id,
+    trigger: fields.trigger ?? {}, // {files:[glob], symbols:[], action, keywords:[]}
+    scope: fields.scope ?? "repo", // symbol | dir | repo | global
+    whatWentWrong: fields.whatWentWrong ?? "",
+    correctedBehavior: fields.correctedBehavior ?? "",
+    evidenceCount: 0,
+    contradictionCount: 0,
+    quarantineReconfirms: 0,
+    status: "candidate", // candidate | active | quarantined | retired
+    createdDay: nowDay,
+    lastConfirmedDay: nowDay,
+    halfLifeDays: fields.halfLifeDays ?? 45,
+    provenance: fields.provenance ?? { episodes: [], signals: [] },
+  };
+}
+
+/**
+ * Validity — the paper's `val` term (Eq. retrieve, §7.1). The Laplace-smoothed Beta posterior
+ * mean over GROUND-TRUTH outcomes: how much independent evidence upholds this lesson vs.
+ * contradicts it, with NO time decay. This is what makes a memory pruned by whether its
+ * prediction later held (a test/commit), not by the model's own say-so.
+ */
+export function validity(lesson) {
+  const alpha = 1 + (lesson.evidenceCount ?? 0);
+  const beta = 1 + (lesson.contradictionCount ?? 0);
+  return alpha / (alpha + beta);
+}
+
+/** Freshness — the paper's `rec` term: exponential recency decay since last confirmation. */
+export function freshness(lesson, nowDay) {
+  const age = Math.max(0, nowDay - lesson.lastConfirmedDay);
+  return 0.5 ** (age / lesson.halfLifeDays);
+}
+
+/** Time-decayed Beta posterior mean = freshness × validity. Unconfirmed lessons fade out. */
+export function confidenceOf(lesson, nowDay) {
+  return freshness(lesson, nowDay) * validity(lesson);
+}
+
+/** Independent outcome re-confirmed this lesson. Raises confidence with diminishing returns. */
+export function confirm(lesson, nowDay) {
+  const next = {
+    ...lesson,
+    evidenceCount: lesson.evidenceCount + 1,
+    lastConfirmedDay: nowDay,
+  };
+  if (lesson.status === "quarantined") {
+    const reconfirms = lesson.quarantineReconfirms + 1;
+    const back = reconfirms >= 2;
+    return {
+      ...next,
+      quarantineReconfirms: back ? 0 : reconfirms,
+      status: back ? "active" : "quarantined",
+    };
+  }
+  return { ...next, status: "active" };
+}
+
+/** An independent outcome contradicted this lesson. Contradiction is cheaper than confirmation. */
+export function contradict(lesson, nowDay) {
+  const next = { ...lesson, contradictionCount: lesson.contradictionCount + 1 };
+  if (lesson.status === "quarantined") return { ...next, status: "retired" };
+  if (confidenceOf(next, nowDay) < 0.3) return { ...next, status: "quarantined" };
+  return next;
+}
+
+/** Compile a `*` / `**` glob to an anchored RegExp (no sentinel chars — single pass). */
+const globToRe = (glob) => {
+  const body = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*|\*/g, (m) => (m === "**" ? ".*" : "[^/]*"));
+  return new RegExp(`^${body}$`);
+};
+
+/** Trigger overlap with the current context, in [0,1]: symbol hit beats file beats keyword. */
+export function matchScore(lesson, context) {
+  const t = lesson.trigger;
+  if (t.symbols?.some((s) => context.symbols?.includes(s))) return 1.0;
+  if (t.files?.some((g) => context.files?.some((f) => globToRe(g).test(f)))) return 0.6;
+  if (t.keywords?.some((k) => context.keywords?.includes(k))) return 0.3;
+  return 0;
+}
+
+/**
+ * Select the lessons worth injecting for the current files/symbols — relevance-ranked and
+ * hard-capped. Overflow becomes a POINTER, never a silent drop (the #39811 cliff lesson).
+ * @returns {{selected:object[], overflow:number, block:string}}
+ */
+export function selectForInjection(lessons, context, { budget = 12, nowDay = 0 } = {}) {
+  const ranked = lessons
+    .filter((l) => l.status === "active")
+    .map((l) => ({ lesson: l, m: matchScore(l, context) }))
+    .filter((x) => x.m > 0)
+    .map((x) => {
+      // The paper's retrieval score, decomposed into named terms: relevance (match) ×
+      // freshness (rec) × validity (val, ground-truth outcomes) × scope, with a small recency
+      // boost. Making `val` explicit ranks outcome-confirmed lessons above merely-recent ones.
+      const rel = x.m;
+      const rec = freshness(x.lesson, nowDay);
+      const val = validity(x.lesson);
+      const scopeW = SCOPE_WEIGHT[x.lesson.scope] ?? 0.5;
+      const recencyBoost = 1 + (nowDay - x.lesson.lastConfirmedDay <= 14 ? 0.2 : 0);
+      return { lesson: x.lesson, score: rel * rec * val * scopeW * recencyBoost };
+    })
+    .sort((a, b) => b.score - a.score);
+
+  const selected = ranked.slice(0, budget).map((x) => x.lesson);
+  const overflow = Math.max(0, ranked.length - selected.length);
+  const rows = selected.map((l) => `- **${l.id}** — ${l.correctedBehavior}`.slice(0, 200));
+  if (overflow) rows.push(`- _(+${overflow} more matched lessons in .forge/lessons/ — not shown)_`);
+  const block = selected.length
+    ? [
+        "## Lessons for the files in play (Forge Cortex)",
+        "Background context from past mistakes on this repo — verify before acting.",
+        "",
+        ...rows,
+        "",
+      ].join("\n")
+    : "";
+  return { selected, overflow, block };
+}

package/src/lessons_store.js

@@ -0,0 +1,137 @@
+// forge lessons storage — persistence for the self-correcting core. Lessons are one
+// file each under .forge/lessons/ (git-committable, human-auditable), episodes are an
+// append-only JSONL. Flat front-matter, not YAML: zero runtime deps and still readable/
+// diffable. Secret-refusal is reused from recall (never persist a credential).
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { SECRET_RE } from "./recall.js";
+
+export const lessonsDir = (root = process.cwd()) => join(root, ".forge", "lessons");
+
+const csv = (arr) => (arr ?? []).join(", ");
+const listOf = (v) =>
+  v
+    ? v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+/** Pure: lesson object → file text (flat front-matter + markdown body). */
+export function serialize(lesson) {
+  const t = lesson.trigger ?? {};
+  const fm = [
+    `id: ${lesson.id}`,
+    `status: ${lesson.status}`,
+    `scope: ${lesson.scope}`,
+    `trigger.files: ${csv(t.files)}`,
+    `trigger.symbols: ${csv(t.symbols)}`,
+    `trigger.keywords: ${csv(t.keywords)}`,
+    `trigger.action: ${t.action ?? ""}`,
+    `evidence: ${lesson.evidenceCount}`,
+    `contradiction: ${lesson.contradictionCount}`,
+    `quarantineReconfirms: ${lesson.quarantineReconfirms}`,
+    `created: ${lesson.createdDay}`,
+    `lastConfirmed: ${lesson.lastConfirmedDay}`,
+    `halfLifeDays: ${lesson.halfLifeDays}`,
+    `episodes: ${csv(lesson.provenance?.episodes)}`,
+    `signals: ${csv(lesson.provenance?.signals)}`,
+  ].join("\n");
+  return `---\n${fm}\n---\n\n${lesson.whatWentWrong}\n\n**Fix:** ${lesson.correctedBehavior}\n`;
+}
+
+/** Pure: file text → lesson object (inverse of serialize). */
+export function parse(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) throw new Error("invalid lesson file (no front-matter)");
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  const body = m[2].trim();
+  const [whatWentWrong] = body.split(/\n\n\*\*Fix:\*\*/);
+  const fix = body.match(/\*\*Fix:\*\*\s*([\s\S]*)$/);
+  return {
+    id: fm.id,
+    status: fm.status,
+    scope: fm.scope,
+    trigger: {
+      files: listOf(fm["trigger.files"]),
+      symbols: listOf(fm["trigger.symbols"]),
+      keywords: listOf(fm["trigger.keywords"]),
+      action: fm["trigger.action"] || undefined,
+    },
+    whatWentWrong: whatWentWrong.trim(),
+    correctedBehavior: fix ? fix[1].trim() : "",
+    evidenceCount: Number(fm.evidence) || 0,
+    contradictionCount: Number(fm.contradiction) || 0,
+    quarantineReconfirms: Number(fm.quarantineReconfirms) || 0,
+    createdDay: Number(fm.created) || 0,
+    lastConfirmedDay: Number(fm.lastConfirmed) || 0,
+    halfLifeDays: Number(fm.halfLifeDays) || 45,
+    provenance: { episodes: listOf(fm.episodes), signals: listOf(fm.signals) },
+  };
+}
+
+/** Persist one lesson. Refuses secret-like content (store a pointer, never the value). */
+export function save(root, lesson) {
+  const text = serialize(lesson);
+  if (SECRET_RE.test(text)) {
+    return {
+      ok: false,
+      reason: "refused: lesson looks like it contains a secret/credential",
+    };
+  }
+  const dir = lessonsDir(root);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${lesson.id}.md`), text);
+  return { ok: true };
+}
+
+/** Load every persisted lesson (episodes.jsonl is skipped — only .md files are lessons).
+ *  A single malformed/half-written file is skipped, not fatal — one bad file must never take
+ *  down memory retrieval, routing, and the pre-edit advisory (everywhere `load` is called). */
+export function load(root) {
+  const dir = lessonsDir(root);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .sort()) {
+    try {
+      out.push(parse(readFileSync(join(dir, f), "utf8")));
+    } catch (err) {
+      if (process.env.FORGE_DEBUG === "1")
+        process.stderr.write(`forge lessons: skipping ${f}: ${err?.message ?? err}\n`);
+    }
+  }
+  return out;
+}
+
+/** Append a correction episode to the audit log (independent evidence, never overwritten). */
+export function appendEpisode(root, episode) {
+  const dir = lessonsDir(root);
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "episodes.jsonl"), `${JSON.stringify(episode)}\n`);
+}
+
+export function readEpisodes(root) {
+  const path = join(lessonsDir(root), "episodes.jsonl");
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line)); // one corrupt JSONL line must not discard the whole log
+    } catch {}
+  }
+  return out;
+}