@codewithjuber/forgekit 0.8.0

package/src/context.js

@@ -0,0 +1,273 @@
+// forge context — context assembly as a budgeted optimization with a completeness
+// gate (docs/plans/substrate-v2/04-context-assembly.md). Two failures die here:
+// over-stuffing (everything competes for the window on equal terms — P3 of the
+// paper) and under-supplying (the agent edits a symbol without its callers, tests,
+// or the team's lessons, then "assumes"). Selection gets an objective function
+// (greedy knapsack by value density, with a compression ladder instead of silent
+// drops) and sufficiency becomes a COMPUTED SET: required knowledge R(edit) from
+// the atlas, missing = R \ covered — auto-fetched when resolvable, asked as a
+// derived M2 question when not. Context insufficiency stops being a feeling.
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { has as atlasHas, query as atlasQuery, impact } from "./atlas.js";
+import { claimText, val } from "./ledger.js";
+import { loadClaims, repoLedger } from "./ledger_store.js";
+import { referencedEntities } from "./preflight.js";
+
+/** chars → tokens heuristic (calibrated in P8; consistent with the reuse estimator). */
+export const tokensOf = (text) => Math.ceil(String(text).length / 3.6);
+
+/** Lessons must be THIS trusted to enter the required set (spec §3: lessons*(S)). */
+export const LESSON_REQUIRED_VAL = 0.8;
+/** Per-source diminishing returns for optional items (spec §2). */
+const SOURCE_DISCOUNT = 0.7;
+/** Default assembly budget in tokens (callers pass the real per-tool cap). */
+export const DEFAULT_BUDGET = 6000;
+
+const readRel = (root, rel) => {
+  try {
+    return readFileSync(join(root, rel), "utf8");
+  } catch {
+    return null;
+  }
+};
+
+// Sibling-test detection (same heuristics family as substrate's predictFailingTests,
+// local here to keep the import graph one-directional: substrate → context, never back).
+const isTestFile = (f) => /(\.|_)(test|spec)\.[jt]sx?$|(^|\/)(tests?|__tests__)\//.test(f);
+function siblingTests(root, file) {
+  const dir = dirname(file);
+  const base = basename(file).replace(/\.[^.]+$/, "");
+  const ext = file.match(/\.[^.]+$/)?.[0] ?? ".js";
+  const candidates = [
+    join(dir, `${base}.test${ext}`),
+    join(dir, `${base}.spec${ext}`),
+    join(dir, "__tests__", `${base}.test${ext}`),
+    join("test", `${base}.test${ext}`),
+    join("tests", `${base}.test${ext}`),
+  ];
+  return candidates.filter((c) => existsSync(join(root, c)));
+}
+
+/**
+ * The required-knowledge set R(edit) — computed, not vibes (spec §3):
+ *   defs(S) ∪ blast₁(S) ∪ tests(S) ∪ lessons*(S)
+ * Each entry: { key, kind, name, resolvable } — unresolvable entries are exactly the
+ * derived clarifying questions.
+ */
+export function requiredSet(root, task, { atlas = null, claims = [], nowDay = 0 } = {}) {
+  const entities = referencedEntities(String(task || ""));
+  const R = [];
+  const targetFiles = new Set();
+
+  for (const s of entities.symbols) {
+    const known = atlas ? atlasHas(atlas, s) : false;
+    R.push({ key: `def:${s}`, kind: "def", name: s, resolvable: known });
+    if (known)
+      for (const hit of atlasQuery(atlas, s))
+        if (hit.name === s || hit.qname === s) targetFiles.add(hit.file);
+    if (known) R.push({ key: `deps:${s}`, kind: "deps", name: s, resolvable: true });
+  }
+  for (const f of entities.files) {
+    const onDisk = existsSync(join(root, f));
+    R.push({ key: `file:${f}`, kind: "file", name: f, resolvable: onDisk });
+    if (onDisk) targetFiles.add(f);
+  }
+  for (const f of targetFiles) {
+    if (isTestFile(f)) continue;
+    for (const t of siblingTests(root, f))
+      R.push({ key: `tests:${t}`, kind: "tests", name: t, resolvable: true });
+  }
+  // Team lessons trusted past the floor, scope-matching the targets — required context:
+  // an agent editing without them repeats a mistake the ledger already paid for.
+  const names = new Set([...entities.symbols, ...entities.files.map((f) => basename(f))]);
+  for (const c of claims) {
+    if (c.kind !== "lesson" || c.tombstone || val(c, nowDay) < LESSON_REQUIRED_VAL) continue;
+    const trig = [...(c.body.trigger?.symbols ?? []), ...(c.body.trigger?.files ?? [])];
+    if (trig.some((t) => names.has(t) || names.has(basename(String(t)))))
+      R.push({ key: `lesson:${c.id.slice(0, 8)}`, kind: "lesson", name: c.id, resolvable: true });
+  }
+  // Dedupe by key, deterministic order.
+  const seen = new Set();
+  return R.filter((r) => (seen.has(r.key) ? false : seen.add(r.key))).sort((a, b) =>
+    a.key < b.key ? -1 : 1,
+  );
+}
+
+// An item is one injectable unit with a COMPRESSION LADDER: granularity variants from
+// full text down to a one-line pointer. The optimizer may downgrade an item instead of
+// dropping it — compression is a lossy move with a known cost, chosen explicitly,
+// never by scroll-off (spec §2).
+function fileItem(root, rel, { covers, source, score }) {
+  const text = readRel(root, rel);
+  if (text === null) return null;
+  const head = text.split("\n").slice(0, 25).join("\n");
+  const variants = [
+    { gran: "full", text: `// ${rel}\n${text}`, tokens: tokensOf(text) },
+    { gran: "head", text: `// ${rel} (first 25 lines)\n${head}`, tokens: tokensOf(head) },
+    { gran: "pointer", text: `- read ${rel}`, tokens: 8 },
+  ];
+  return { id: `${source}:${rel}`, source, covers, score, variants };
+}
+
+/**
+ * Assemble the context for a task: pinned required items (downgraded before dropped),
+ * optional items greedily by value density, and the missing set as derived questions.
+ * @param {string} root
+ * @param {string} task
+ * @param {{budget?:number, atlas?:any, claims?:any[], nowDay?:number}} [opts]
+ */
+export function assemble(
+  root,
+  task,
+  { budget = DEFAULT_BUDGET, atlas = null, claims, nowDay = 0 } = {},
+) {
+  const ledgerDir = repoLedger(root);
+  const allClaims = claims ?? (existsSync(join(ledgerDir, "claims")) ? loadClaims(ledgerDir) : []);
+  const required = requiredSet(root, task, { atlas, claims: allClaims, nowDay });
+
+  // --- build candidate items, keyed by what they cover -------------------------------
+  const items = [];
+  for (const r of required) {
+    if (!r.resolvable) continue;
+    if (r.kind === "def") {
+      const hit = atlasQuery(atlas, r.name).find((s) => s.name === r.name || s.qname === r.name);
+      if (hit?.file) {
+        const it = fileItem(root, hit.file, { covers: [r.key], source: "def", score: 1 });
+        if (it) items.push(it);
+      }
+    } else if (r.kind === "file") {
+      const it = fileItem(root, r.name, { covers: [r.key], source: "def", score: 1 });
+      if (it) items.push(it);
+    } else if (r.kind === "tests") {
+      const it = fileItem(root, r.name, { covers: [r.key], source: "tests", score: 0.9 });
+      if (it) items.push(it);
+    } else if (r.kind === "deps" && atlas) {
+      const hop1 = impact(atlas, r.name, { maxHops: 1 })
+        .impacted.filter((x) => x.hopDistance === 1)
+        .slice(0, 12);
+      const text = hop1.length
+        ? [
+            `direct dependents of ${r.name} (edit these with it or verify them):`,
+            ...hop1.map((x) => `  - ${x.node.name} (${x.node.file}, via ${x.edgeKinds[0]})`),
+          ].join("\n")
+        : `no direct dependents of ${r.name} found in the atlas`;
+      items.push({
+        id: `deps:${r.name}`,
+        source: "deps",
+        covers: [r.key],
+        score: 1,
+        variants: [{ gran: "full", text, tokens: tokensOf(text) }],
+      });
+    } else if (r.kind === "lesson") {
+      const c = allClaims.find((x) => x.id === r.name);
+      if (c) {
+        const text = `lesson (val ${val(c, nowDay).toFixed(2)}): ${c.body.correctedBehavior}`;
+        items.push({
+          id: `lesson:${c.id.slice(0, 8)}`,
+          source: "lesson",
+          covers: [r.key],
+          score: 0.95,
+          variants: [{ gran: "full", text, tokens: tokensOf(text) }],
+        });
+      }
+    }
+  }
+  // Optional extras: trusted scope-matching facts (nice-to-have, never required).
+  for (const c of allClaims) {
+    if (c.kind !== "fact" || c.tombstone) continue;
+    const v = val(c, nowDay);
+    if (v < 0.5) continue;
+    const text = `fact: ${claimText(c)}`;
+    items.push({
+      id: `fact:${c.id.slice(0, 8)}`,
+      source: "fact",
+      covers: [],
+      score: 0.3 + 0.4 * v,
+      variants: [{ gran: "full", text, tokens: tokensOf(text) }],
+    });
+  }
+
+  // A symbol's definition and an explicitly named file often resolve to the SAME file —
+  // merge items by id (union of covered keys) so one span never gets injected twice.
+  const byId = new Map();
+  for (const it of items) {
+    const prev = byId.get(it.id);
+    if (prev) {
+      prev.covers = [...new Set([...prev.covers, ...it.covers])];
+      prev.score = Math.max(prev.score, it.score);
+    } else byId.set(it.id, it);
+  }
+  const merged = [...byId.values()];
+
+  // --- selection: pin required coverage, downgrade before dropping -------------------
+  const pinned = merged.filter((i) => i.covers.length);
+  const optional = merged
+    .filter((i) => !i.covers.length)
+    .sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : 1));
+  const chosen = pinned.map((i) => ({ item: i, v: 0 })); // v = variant index
+  const used = () => chosen.reduce((n, c) => n + c.item.variants[c.v].tokens, 0);
+  // Downgrade the largest pinned item one rung at a time until the pins fit the budget.
+  while (used() > budget) {
+    const cand = chosen
+      .filter((c) => c.v < c.item.variants.length - 1)
+      .sort((a, b) => b.item.variants[b.v].tokens - a.item.variants[a.v].tokens)[0];
+    if (!cand) break; // everything is already a pointer — required coverage beats budget
+    cand.v++;
+  }
+  // Greedy fill by value density with per-source diminishing returns.
+  const perSource = {};
+  for (const item of optional) {
+    const variant = item.variants[0];
+    const discount = SOURCE_DISCOUNT ** (perSource[item.source] ?? 0);
+    if (used() + variant.tokens > budget) continue;
+    chosen.push({ item, v: 0 });
+    perSource[item.source] = (perSource[item.source] ?? 0) + 1;
+    if (discount < 0.2) break; // fourth+ item from one source: value has decayed away
+  }
+
+  const covered = new Set(chosen.flatMap((c) => c.item.covers));
+  const missing = required.filter((r) => !r.resolvable || !covered.has(r.key));
+  const questions = missing
+    .filter((r) => !r.resolvable)
+    .map((r) =>
+      r.kind === "def"
+        ? `The task names \`${r.name}\` but the repo doesn't define it — which file implements it (or is it new)?`
+        : `The task names \`${r.name}\` but that file doesn't exist — where should this live?`,
+    );
+
+  return {
+    ok: missing.length === 0,
+    budget,
+    tokens: used(),
+    required: required.map((r) => r.key),
+    covered: [...covered].sort(),
+    missing: missing.map((r) => r.key),
+    questions,
+    selection: chosen.map((c) => ({
+      id: c.item.id,
+      source: c.item.source,
+      gran: c.item.variants[c.v].gran,
+      tokens: c.item.variants[c.v].tokens,
+    })),
+    block: chosen.map((c) => c.item.variants[c.v].text).join("\n\n"),
+  };
+}
+
+/** Human rendering for `forge context`. */
+export function renderContext(r) {
+  const lines = ["Forge context — budgeted assembly + completeness gate", ""];
+  lines.push(
+    `  budget: ${r.tokens}/${r.budget} tokens · required ${r.required.length} · ${r.ok ? "COMPLETE" : "INCOMPLETE"}`,
+  );
+  for (const s of r.selection) lines.push(`    + ${s.id} [${s.gran}] ${s.tokens}t`);
+  if (r.missing.length) {
+    lines.push("", "  missing (computed, not a feeling):");
+    for (const m of r.missing) lines.push(`    - ${m}`);
+  }
+  if (r.questions.length) {
+    lines.push("", "  ask before acting:");
+    for (const q of r.questions) lines.push(`    ? ${q}`);
+  }
+  return lines.join("\n");
+}

package/src/cortex.js

@@ -0,0 +1,251 @@
+// forge cortex — orchestration that ties the pure core (lessons.js) to storage
+// (lessons_store.js). This is what the hooks (Layer 0) call: a scored signal-cluster
+// becomes a created/confirmed lesson; an independent human reversal becomes a
+// contradiction. Kept fs-thin and deterministic (day + ids passed in) so it's testable
+// without any hook wiring.
+
+import { recordLessonEvent, supersedeLessonClaim } from "./ledger_bridge.js";
+import { mergedLessons } from "./ledger_read.js";
+import {
+  confidenceOf,
+  confirm,
+  contradict,
+  matchScore,
+  newLesson,
+  scoreMistake,
+  selectForInjection,
+} from "./lessons.js";
+import { appendEpisode, load, readEpisodes, save } from "./lessons_store.js";
+import { slug } from "./util.js";
+
+const lessonIdFor = (ctx) => `lsn_${slug(ctx.symbols?.[0] || ctx.files?.[0] || "ctx") || "ctx"}`;
+
+/** Two contexts overlap if they share any file or symbol. */
+const overlaps = (a, b) => {
+  const files = new Set(a.files ?? []);
+  const symbols = new Set(a.symbols ?? []);
+  return (b.files ?? []).some((f) => files.has(f)) || (b.symbols ?? []).some((s) => symbols.has(s));
+};
+
+/** Lessons whose trigger overlaps the current context, in the given lifecycle states. */
+export function matchingLessons(
+  lessons,
+  context,
+  statuses = ["active", "candidate", "quarantined"],
+) {
+  return lessons.filter((l) => statuses.includes(l.status) && matchScore(l, context) > 0);
+}
+
+// Deterministic fallback when no LLM distiller ran (the Stop-hook distiller replaces this).
+function templateDistill(context) {
+  const sym = context.symbols?.[0];
+  const where = sym ? `\`${sym}\`` : context.files?.[0] ? `\`${context.files[0]}\`` : "this code";
+  return {
+    whatWentWrong: `An edit to ${where} was corrected (repeated / reverted / broke a check).`,
+    correctedBehavior: sym
+      ? `Before editing ${where}, check its callers and tests first.`
+      : `Slow down on ${where}: re-read and check impact before editing.`,
+  };
+}
+
+/**
+ * Record a correction episode. If the signals clear the mistake bar, create a new
+ * candidate lesson (first occurrence) or confirm the matching one (a recurrence — the
+ * only thing that promotes a lesson toward `active`). Always logs the episode.
+ * @param {string} root
+ * @param {{signals:{signal:string}[], context:object, nowDay:number, episodeId:string, distilled?:{whatWentWrong:string, correctedBehavior:string}}} opts
+ * @returns {{action:string, id?:string, status?:string, p:number, fires:boolean}}
+ */
+export function recordMistake(root, { signals, context, nowDay, episodeId, distilled }) {
+  const { p, fires } = scoreMistake(signals);
+  // A weak-but-firing episode (0.4–0.7) only earns a lesson if the same context already
+  // misfired before — recurrence, not a single shot. Check BEFORE logging this episode.
+  const recurredWeak = readEpisodes(root).some(
+    (e) => e.kind === "mistake" && overlaps(e.context ?? {}, context),
+  );
+  appendEpisode(root, {
+    id: episodeId,
+    kind: "mistake",
+    signals: signals.map((s) => s.signal),
+    p,
+    context,
+    day: nowDay,
+  });
+  const strong = fires && p >= 0.7;
+  const accumulated = fires && p >= 0.4 && recurredWeak;
+  if (!strong && !accumulated) return { action: "logged", p, fires };
+
+  // Deliberately LEGACY-ONLY (not mergedLessons): this lookup decides confirm-vs-create
+  // for a LOCAL write. A teammate's merged ledger claim has no local file, and letting it
+  // match would swallow a fresh local mistake into confirm() — which edits a legacy file
+  // that doesn't exist — and hang the shadow evidence ref (#n<count>) off counters this
+  // repo never owned. Creating locally is correct AND convergent: the new lesson's shadow
+  // claim content-addresses to the teammate's claim, so both sides' evidence lands on ONE
+  // claim at the next `forge ledger merge`.
+  const existing = matchingLessons(load(root), context)[0];
+  if (existing) {
+    const c = confirm(existing, nowDay);
+    const updated = {
+      ...c,
+      provenance: {
+        ...c.provenance,
+        episodes: [...(c.provenance?.episodes ?? []), episodeId],
+      },
+    };
+    if (!save(root, updated).ok) return { action: "refused", p, fires };
+    // Shadow the confirmation into the PCM ledger (best-effort by design, never blocks
+    // the hook — reads are merged via ledger_read.js since P2). The evidence counter
+    // rides in the ref because episode ids reset per session (ep_m0_…) — without it,
+    // two same-day sessions confirming via the same file would hash identically and
+    // the second real confirmation would be silently deduped away.
+    recordLessonEvent(root, updated, {
+      result: "confirm",
+      ref: `episode:${episodeId}#n${updated.evidenceCount}`,
+      t: nowDay,
+    });
+    return {
+      action: "confirmed",
+      id: updated.id,
+      status: updated.status,
+      p,
+      fires,
+    };
+  }
+
+  const d = distilled ?? templateDistill(context);
+  const lesson = newLesson(
+    {
+      id: lessonIdFor(context),
+      trigger: {
+        symbols: context.symbols ?? [],
+        files: context.files ?? [],
+        keywords: context.keywords ?? [],
+        action: "edit",
+      },
+      scope: context.symbols?.length ? "symbol" : "repo",
+      whatWentWrong: d.whatWentWrong,
+      correctedBehavior: d.correctedBehavior,
+      provenance: {
+        episodes: [episodeId],
+        signals: signals.map((s) => s.signal),
+      },
+    },
+    nowDay,
+  );
+  // Report "created" only when the write actually landed — a refused save (e.g. secret-bearing
+  // body) must not make the hook believe a lesson exists and try to distill a phantom.
+  if (!save(root, lesson).ok) return { action: "refused", p, fires };
+  // Mint-only shadow: a freshly created lesson has zero evidence (creation is not
+  // confirmation — the ledger's val starts at the 0.5 prior, same as newLesson).
+  recordLessonEvent(root, lesson, { t: nowDay });
+  return { action: "created", id: lesson.id, status: lesson.status, p, fires };
+}
+
+/**
+ * An independent human reversal (e.g. `git revert` of what a lesson advised) contradicts
+ * every matching active/quarantined lesson — the anti-self-reinforcement path.
+ */
+export function recordContradiction(root, { context, nowDay, episodeId }) {
+  appendEpisode(root, {
+    id: episodeId,
+    kind: "contradiction",
+    context,
+    day: nowDay,
+  });
+  // Legacy-only for the same reason as recordMistake: contradict() saves the legacy
+  // file, so only lessons that HAVE one are targets. A teammate's claim still converges
+  // — the same reversal, recurring locally, mints the local twin whose evidence merges.
+  const targets = matchingLessons(load(root), context, ["active", "quarantined"]);
+  const results = targets.map((l) => {
+    const updated = contradict(l, nowDay);
+    const saved = save(root, updated).ok;
+    // Shadowed at the conservative bridge weight, NOT human.revert (w=1.0): the hook's
+    // revert detection is regex-based and matches routine `git restore`s, and a
+    // full-weight contradiction would permanently anchor the claim near dormancy in an
+    // append-only log. The counter in the ref keeps distinct same-day events distinct.
+    if (saved)
+      recordLessonEvent(root, updated, {
+        result: "contradict",
+        ref: `episode:${episodeId}#c${updated.contradictionCount}`,
+        t: nowDay,
+      });
+    return { id: updated.id, status: updated.status, saved };
+  });
+  return { action: "contradicted", results };
+}
+
+/** The injection block for the current context — what a SessionStart/PreToolUse hook emits.
+ *  Reads the MERGED view (P2 read flip): teammate lessons that arrived via
+ *  `forge ledger merge` inject alongside local ones. */
+export function lessonsForContext(root, context, opts = {}) {
+  return selectForInjection(mergedLessons(root, opts.nowDay ?? 0), context, opts);
+}
+
+/** Repo-wide top active lessons — what a SessionStart hook injects (no file context yet).
+ *  Merged view: a teammate's outcome-confirmed lesson surfaces here too. */
+export function startupBlock(root, nowDay = 0, budget = 8) {
+  const active = mergedLessons(root, nowDay).filter((l) => l.status === "active");
+  if (!active.length) return "";
+  const ranked = active
+    .map((l) => ({ lesson: l, conf: confidenceOf(l, nowDay) }))
+    .sort((a, b) => b.conf - a.conf);
+  const shown = ranked.slice(0, budget);
+  const rows = shown.map((x) =>
+    `- **${x.lesson.id}** — ${x.lesson.correctedBehavior}`.slice(0, 200),
+  );
+  const overflow = active.length - shown.length;
+  if (overflow > 0) rows.push(`- _(+${overflow} more active lessons — run \`forge cortex\`)_`);
+  return [
+    "## Lessons learned on this repo (Forge Cortex)",
+    "Background context from past corrections on this repo — verify before acting, don't blindly obey.",
+    "",
+    ...rows,
+    "",
+  ].join("\n");
+}
+
+/** Replace a lesson's body with a model-distilled version (false if not found or the save was
+ *  refused — e.g. the distilled text tripped secret-refusal). */
+export function applyDistillation(root, lessonId, distilled) {
+  if (!distilled) return false;
+  // Legacy-only read: distillation EDITS the legacy file, so only file-backed lessons apply.
+  const lesson = load(root).find((l) => l.id === lessonId);
+  if (!lesson) return false;
+  const updated = {
+    ...lesson,
+    whatWentWrong: distilled.whatWentWrong,
+    correctedBehavior: distilled.correctedBehavior,
+  };
+  const ok = save(root, updated).ok;
+  // A body rewrite changes the content-addressed claim id — supersede in the ledger
+  // (mint the distilled claim, carry the evidence over, tombstone the template claim)
+  // or the lesson's history splits across two disjoint claims.
+  if (ok) supersedeLessonClaim(root, lesson, updated);
+  return ok;
+}
+
+/** The lessons block to inline into AGENTS.md so non-Claude tools see them (empty if none). */
+export function cortexBlock(targetRoot = process.cwd()) {
+  return startupBlock(targetRoot, Math.floor(Date.now() / 86400000));
+}
+
+/** Auditable snapshot for `forge cortex status` — merged view, like every read surface. */
+export function summary(root, nowDay = 0) {
+  const lessons = mergedLessons(root, nowDay);
+  const by = (s) => lessons.filter((l) => l.status === s).length;
+  return {
+    total: lessons.length,
+    active: by("active"),
+    candidate: by("candidate"),
+    quarantined: by("quarantined"),
+    retired: by("retired"),
+    topActive: lessons
+      .filter((l) => l.status === "active")
+      .map((l) => ({
+        id: l.id,
+        confidence: Number(confidenceOf(l, nowDay).toFixed(2)),
+      }))
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, 10),
+  };
+}

package/src/cortex_distill.js

@@ -0,0 +1,55 @@
+// forge cortex distiller — turn a raw correction episode into a real, useful lesson via a
+// cheap model call, instead of the deterministic template. OPT-IN (ENABLE_CORTEX_DISTILL=1)
+// and fail-safe: any failure returns null and the caller keeps the template. Zero deps — it
+// shells out to the `claude` CLI via the shared adjudicate runner (same primitive every other
+// faculty uses); the runner is injectable so the pure prompt/parse logic is testable without it.
+import { buildRunner } from "./adjudicate.js";
+import { SECRET_RE } from "./recall.js";
+
+/**
+ * Pure: build the distillation prompt from an episode.
+ * @param {{context?:{symbols?:string[], files?:string[]}, signals?:string[]}} episode
+ */
+export function buildPrompt({ context = {}, signals = [] }) {
+  const where = context.symbols?.[0] || context.files?.[0] || "some code";
+  return `A coding agent just made and then corrected a mistake on this repository.
+Observed correction signals: ${signals.join(", ") || "n/a"}.
+Location: ${where}.
+Write ONE short, durable lesson that would stop this mistake recurring. Respond with STRICT
+JSON and nothing else:
+{"whatWentWrong":"<concrete, <=140 chars>","correctedBehavior":"<an imperative rule, <=140 chars>"}
+Do not include secrets, tokens, keys, or PII. No text outside the JSON object.`;
+}
+
+/** Pure: extract {whatWentWrong, correctedBehavior} from model output, or null if unusable. */
+export function parseDistilled(text) {
+  if (!text) return null;
+  const match = String(text).match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  let obj;
+  try {
+    obj = JSON.parse(match[0]);
+  } catch {
+    return null;
+  }
+  const whatWentWrong = String(obj.whatWentWrong ?? "")
+    .trim()
+    .slice(0, 200);
+  const correctedBehavior = String(obj.correctedBehavior ?? "")
+    .trim()
+    .slice(0, 200);
+  if (!whatWentWrong || !correctedBehavior) return null;
+  if (SECRET_RE.test(`${whatWentWrong} ${correctedBehavior}`)) return null; // never persist a secret
+  return { whatWentWrong, correctedBehavior };
+}
+
+const claudeRun = (prompt, opts = {}) => buildRunner(opts)(prompt);
+
+/** Distill an episode into a lesson body. Returns null on any failure (caller keeps template). */
+export function distill(episode, { run = claudeRun } = {}) {
+  try {
+    return parseDistilled(run(buildPrompt(episode)));
+  } catch {
+    return null;
+  }
+}

package/src/cortex_features.js

@@ -0,0 +1,81 @@
+// forge cortex features — turn a real edit into the predictor's feature vector. The pure
+// computeFeatures() is fully testable; featuresForEdit() fills it from actual repo state
+// (lessons + git) with graceful degradation. caller_fanout / no_caller_update are SEAMS: a
+// zero-dep grep gives a rough fan-out today; adopting a graph MCP (agent-lsp/Serena) drops
+// a precise call graph straight in without touching the predictor.
+import { execFileSync } from "node:child_process";
+import { confidenceOf, matchScore } from "./lessons.js";
+import { load } from "./lessons_store.js";
+
+/**
+ * Pure: edit + gathered signals → the predictor feature vector (all features in [0,1]).
+ * @param {{file?:string, symbol?:string}} edit
+ * @param {{callerCount?:number, churnCommits?:number, hasTest?:boolean, signatureChange?:boolean, callersInDiff?:boolean, activeLessons?:object[], nowDay?:number}} deps
+ */
+export function computeFeatures(edit, deps = {}) {
+  const {
+    callerCount = 0,
+    churnCommits = 0,
+    hasTest = true,
+    signatureChange = false,
+    callersInDiff = true,
+    activeLessons = [],
+    nowDay = 0,
+  } = deps;
+  const ctx = {
+    files: edit.file ? [edit.file] : [],
+    symbols: edit.symbol ? [edit.symbol] : [],
+  };
+  const matched = activeLessons.filter((l) => matchScore(l, ctx) > 0);
+  const lessonMatch = matched.reduce((m, l) => Math.max(m, confidenceOf(l, nowDay)), 0);
+  return {
+    caller_fanout: Math.min(1, callerCount / 10), // >10 callers = maxed out
+    lesson_match: lessonMatch,
+    churn: Math.min(1, churnCommits / 10),
+    test_coverage_gap: hasTest ? 0 : 1,
+    signature_change: signatureChange ? 1 : 0,
+    no_caller_update: signatureChange && !callersInDiff ? 1 : 0,
+    past_mistake_here: matched.some((l) => (l.evidenceCount ?? 0) > 0) ? 1 : 0,
+  };
+}
+
+const tryExec = (bin, args, root) => {
+  try {
+    return execFileSync(bin, args, {
+      cwd: root,
+      encoding: "utf8",
+      timeout: 1500, // bound latency — this runs in a PreToolUse hook on every edit
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return "";
+  }
+};
+
+/** How many commits recently touched this file (git churn) — 0 if not a git repo. */
+export function gitChurn(root, file) {
+  if (!file) return 0;
+  const out = tryExec("git", ["log", "--oneline", "-n", "50", "--", file], root);
+  return out ? out.trim().split("\n").filter(Boolean).length : 0;
+}
+
+/** Rough fan-out: how many files mention the symbol (grep). SEAM for a real call graph. */
+export function grepFanout(root, symbol) {
+  if (!symbol) return 0;
+  const out = tryExec("git", ["grep", "-l", "--", symbol], root);
+  return out ? out.trim().split("\n").filter(Boolean).length : 0;
+}
+
+/** Build the feature vector for a real edit from actual repo state (best-effort, degrades). */
+export function featuresForEdit(root, edit, { nowDay = 0 } = {}) {
+  const activeLessons = load(root).filter((l) => l.status === "active");
+  const callerCount = grepFanout(root, edit.symbol);
+  return computeFeatures(edit, {
+    activeLessons,
+    nowDay,
+    callerCount,
+    churnCommits: gitChurn(root, edit.file),
+    // hasTest / signatureChange / callersInDiff need the diff or a graph — left at safe
+    // defaults until a graph MCP is wired; the predictor already handles missing signal.
+  });
+}