@inetafrica/open-claudia 2.6.36 → 2.6.38

package/core/lessons.js

@@ -0,0 +1,276 @@
+// Lessons tier. The soul holds identity + hard rules (user-owned); the
+// persona holds voice (Open-Claudia-owned). Lessons are the third
+// always-injected layer: a small, bounded set of cross-cutting rules that
+// Open Claudia got WRONG before and was corrected on.
+//
+// Why this exists: every other piece of learned knowledge (pack Stances,
+// entity Notes) is topic-gated — it only loads when the incoming message
+// FTS-matches its tags. That fails precisely when a fact is relevant on an
+// off-topic turn (e.g. the Kazee mobile-deploy mechanism coming up during
+// an hr-hub deploy conversation), and recall keys on the USER's text, not
+// the assistant's own wrong output. So a fact can be perfectly stored and
+// still never surface at the moment it's needed. Lessons fix that by being
+// ALWAYS loaded, like soul and persona.
+//
+// To keep the always-on budget tiny and high-signal, a rule only graduates
+// here after a MISS: the per-turn reviewer (pack-review.js) sees the user
+// correct the assistant or repeat a known fact — proof topic-matching
+// failed for it — and promotes a one-line lesson. Each lesson keeps a
+// "(src: <pack-dir>)" pointer to the pack that holds the full context. The
+// nightly dream dedupes, demotes lessons safely captured in their source
+// pack when over cap, and enforces the count. Lessons are user-editable
+// (/lessons, or the file directly) and never store secrets.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const CONFIG_DIR = require("../config-dir");
+const LESSONS_FILE = process.env.LESSONS_FILE ? path.resolve(process.env.LESSONS_FILE) : path.join(CONFIG_DIR, "lessons.md");
+const LESSONS_META_FILE = path.join(path.dirname(LESSONS_FILE), "lessons.meta.json");
+
+// Count cap is the primary bound (dream enforces it with judgment); the
+// char budget is the hard safety net on what actually gets injected.
+const MAX_LESSONS = Number(process.env.LESSONS_MAX || 20);
+const MAX_LESSON_CHARS = Number(process.env.LESSON_MAX_CHARS || 240);  // per lesson
+const MAX_LESSONS_CHARS = Number(process.env.LESSONS_MAX_CHARS || 3500); // total injected block
+
+const FILE_HEADER = `Lessons learned — always loaded into every conversation.
+One rule per bullet: cross-cutting things I got wrong before and was corrected on.
+Edit freely; keep each to a single line. Optional "(src: <pack-dir>)" points to the pack with the full context.
+`;
+
+// ── parsing ─────────────────────────────────────────────────────────
+
+// Strip the "(src: ...)" pointer so the id is stable across src changes.
+function stripSrc(text) {
+  return String(text || "").replace(/\s*\(src:\s*[^)]*\)\s*$/i, "").trim();
+}
+
+function srcOf(text) {
+  const m = String(text || "").match(/\(src:\s*([^)]+)\)\s*$/i);
+  return m ? m[1].trim() : "";
+}
+
+function normalize(text) {
+  return stripSrc(text).toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function lessonId(text) {
+  return crypto.createHash("sha1").update(normalize(text)).digest("hex").slice(0, 8);
+}
+
+// Parse only top-level "- " bullets; everything else (header lines, blank
+// lines, the user's decorative text) is ignored. Robust to hand-edits.
+function parseLessons(raw) {
+  const out = [];
+  const seen = new Set();
+  for (const line of String(raw || "").split("\n")) {
+    const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const full = m[1].trim();
+    const body = stripSrc(full);
+    if (!body) continue;
+    const id = lessonId(full);
+    if (seen.has(id)) continue; // dedupe identical lessons
+    seen.add(id);
+    out.push({ id, text: body, src: srcOf(full) });
+  }
+  return out;
+}
+
+function readLessons() {
+  try { return parseLessons(fs.readFileSync(LESSONS_FILE, "utf-8")); }
+  catch (e) { return []; }
+}
+
+// ── meta sidecar (lifecycle: origin / created / reinforced / src) ────
+
+function readMeta() {
+  try { return JSON.parse(fs.readFileSync(LESSONS_META_FILE, "utf-8")) || {}; }
+  catch (e) { return {}; }
+}
+
+function writeMeta(meta) {
+  fs.mkdirSync(path.dirname(LESSONS_META_FILE), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(LESSONS_META_FILE, JSON.stringify(meta, null, 2) + "\n", { mode: 0o600 });
+}
+
+// Self-heal: drop meta for lessons that no longer exist, seed defaults for
+// lessons that have none (e.g. hand-added by the user). Idempotent.
+function reconcileMeta(lessons) {
+  lessons = lessons || readLessons();
+  const meta = readMeta();
+  const now = new Date().toISOString();
+  const next = {};
+  let changed = false;
+  for (const l of lessons) {
+    if (meta[l.id]) {
+      next[l.id] = meta[l.id];
+      if (l.src && next[l.id].src !== l.src) { next[l.id].src = l.src; changed = true; }
+    } else {
+      next[l.id] = { origin: "user", created: now, reinforced: 0, reinforcedAt: null, src: l.src || "" };
+      changed = true;
+    }
+  }
+  if (Object.keys(meta).length !== Object.keys(next).length) changed = true;
+  if (changed) writeMeta(next);
+  return next;
+}
+
+// ── serialization ───────────────────────────────────────────────────
+
+function lessonLine(l) {
+  return l.src ? `- ${l.text} (src: ${l.src})` : `- ${l.text}`;
+}
+
+function writeLessons(lessons) {
+  const body = lessons.map(lessonLine).join("\n");
+  const content = FILE_HEADER + "\n" + body + (body ? "\n" : "");
+  fs.mkdirSync(path.dirname(LESSONS_FILE), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(LESSONS_FILE, content, { mode: 0o600 });
+  return LESSONS_FILE;
+}
+
+// ── public API ──────────────────────────────────────────────────────
+
+// Structured list merged with meta, newest first by created.
+function listLessons() {
+  const lessons = readLessons();
+  const meta = reconcileMeta(lessons);
+  return lessons
+    .map((l) => ({ ...l, ...(meta[l.id] || {}) }))
+    .sort((a, b) => String(b.created || "").localeCompare(String(a.created || "")));
+}
+
+// The always-injected block. Highest-priority lessons (most reinforced,
+// then most recently reinforced) survive the char budget. Returns "" when
+// there are none, so the system prompt stays clean on a fresh install.
+function loadLessonsBlock() {
+  const lessons = readLessons();
+  if (lessons.length === 0) return "";
+  const meta = reconcileMeta(lessons);
+  const ranked = lessons.slice().sort((a, b) => {
+    const ma = meta[a.id] || {}, mb = meta[b.id] || {};
+    return (mb.reinforced || 0) - (ma.reinforced || 0)
+      || String(mb.reinforcedAt || "").localeCompare(String(ma.reinforcedAt || ""))
+      || String(mb.created || "").localeCompare(String(ma.created || ""));
+  });
+  const out = [];
+  let used = 0;
+  for (const l of ranked) {
+    const line = lessonLine(l);
+    if (used + line.length + 1 > MAX_LESSONS_CHARS) break;
+    out.push(line);
+    used += line.length + 1;
+  }
+  if (out.length === 0) return "";
+  return out.join("\n");
+}
+
+// Add or reinforce a lesson. Dedupe is by normalized text (id), so the same
+// fact phrased the same way reinforces instead of duplicating. No eviction
+// here — the char budget bounds injection and dream enforces the count cap
+// with judgment, so a hard-won lesson is never silently dropped on add.
+function addLesson({ text, src = "", origin = "reviewer" } = {}) {
+  const body = stripSrc(text);
+  if (!body) return { added: false, reason: "empty" };
+  if (body.length > MAX_LESSON_CHARS) return { added: false, reason: `too long (>${MAX_LESSON_CHARS} chars)` };
+
+  const lessons = readLessons();
+  const id = lessonId(body);
+  const meta = reconcileMeta(lessons);
+  const now = new Date().toISOString();
+  const existing = lessons.find((l) => l.id === id);
+
+  if (existing) {
+    if (src && !existing.src) { existing.src = src; writeLessons(lessons); }
+    const m = meta[id] || { origin, created: now, reinforced: 0, src };
+    m.reinforced = (m.reinforced || 0) + 1;
+    m.reinforcedAt = now;
+    if (src && !m.src) m.src = src;
+    meta[id] = m;
+    writeMeta(meta);
+    return { added: false, reinforced: true, id, count: lessons.length };
+  }
+
+  lessons.push({ id, text: body, src });
+  writeLessons(lessons);
+  meta[id] = { origin, created: now, reinforced: 0, reinforcedAt: null, src };
+  writeMeta(meta);
+  const count = lessons.length;
+  return { added: true, id, count, overCap: count > MAX_LESSONS };
+}
+
+// Rewrite a lesson's text in place, preserving its meta (reinforced count,
+// created, origin). Used by the dream to tighten/merge wording. If the new
+// text collides with another existing lesson, the old one is dropped (the
+// survivor keeps its own meta).
+function editLesson(idOrText, newText, { src } = {}) {
+  const body = stripSrc(newText);
+  if (!body) return { ok: false, reason: "empty" };
+  if (body.length > MAX_LESSON_CHARS) return { ok: false, reason: `too long (>${MAX_LESSON_CHARS})` };
+  const arr = readLessons();
+  const oldId = arr.some((l) => l.id === idOrText) ? idOrText : lessonId(idOrText);
+  const idx = arr.findIndex((l) => l.id === oldId);
+  if (idx === -1) return { ok: false, reason: "not found" };
+  const old = arr[idx];
+  const newId = lessonId(body);
+  const meta = readMeta();
+  if (newId !== oldId && arr.some((l) => l.id === newId)) {
+    arr.splice(idx, 1);            // merge into the existing twin
+    writeLessons(arr);
+    delete meta[oldId];
+    writeMeta(meta);
+    return { ok: true, merged: true, id: newId };
+  }
+  arr[idx] = { id: newId, text: body, src: src != null ? src : old.src };
+  writeLessons(arr);
+  const m = meta[oldId] || { origin: "user", created: new Date().toISOString(), reinforced: 0, reinforcedAt: null, src: old.src };
+  if (oldId !== newId) delete meta[oldId];
+  if (src != null) m.src = src;
+  meta[newId] = m;
+  writeMeta(meta);
+  return { ok: true, id: newId };
+}
+
+function removeLesson(idOrText) {
+  const key = String(idOrText || "").trim();
+  if (!key) return false;
+  const lessons = readLessons();
+  const id = lessons.some((l) => l.id === key) ? key : lessonId(key);
+  const next = lessons.filter((l) => l.id !== id);
+  if (next.length === lessons.length) return false;
+  writeLessons(next);
+  const meta = readMeta();
+  delete meta[id];
+  writeMeta(meta);
+  return true;
+}
+
+// Overwrite from raw text (the /lessons edit path and manual edits). Bounds
+// the total size, then reconciles meta to the new contents.
+function saveLessonsRaw(raw) {
+  const text = String(raw || "");
+  if (text.length > MAX_LESSONS_CHARS * 3) {
+    throw new Error(`lessons file too large (${text.length} chars); trim it`);
+  }
+  fs.mkdirSync(path.dirname(LESSONS_FILE), { recursive: true, mode: 0o700 });
+  // Re-serialize through the parser so the stored form is canonical.
+  writeLessons(parseLessons(text));
+  reconcileMeta();
+  return LESSONS_FILE;
+}
+
+function lessonsExist() {
+  return readLessons().length > 0;
+}
+
+module.exports = {
+  LESSONS_FILE, LESSONS_META_FILE,
+  MAX_LESSONS, MAX_LESSON_CHARS, MAX_LESSONS_CHARS,
+  normalize, lessonId, parseLessons,
+  readLessons, listLessons, loadLessonsBlock,
+  readMeta, writeMeta, reconcileMeta,
+  addLesson, editLesson, removeLesson, saveLessonsRaw, lessonsExist,
+};

package/core/pack-review.js

@@ -9,6 +9,7 @@
 const { spawnSubagent } = require("./subagent");
 const packs = require("./packs");
 const entities = require("./entities");
+const lessons = require("./lessons");
 const packGuard = require("./pack-guard");
 const { redactSensitive } = require("./redact");
 
@@ -17,6 +18,9 @@ const MAX_TEXT_CHARS = 7000;
 const REVIEW_MODEL = process.env.PACK_REVIEW_MODEL || "haiku";
 const MAX_ACTIONS = 2;
 const MAX_ENTITY_ACTIONS = 3;
+// Lessons are precious always-on budget — at most one promotion per turn,
+// and only when the turn shows a genuine miss.
+const MAX_LESSON_ACTIONS = 1;
 
 function enabled() {
   return (process.env.PACK_REVIEW || "on").toLowerCase() !== "off";
@@ -52,14 +56,22 @@ function formatAnnouncement(lines) {
 }
 
 function buildReviewPrompt(userText, assistantText) {
-  const index = packs.listPacks().map((p) =>
-    `- ${p.dir}: ${p.name} — ${p.description}${p.tags.length ? ` [${p.tags.join(", ")}]` : ""}`
-  ).join("\n") || "(none yet)";
+  const index = packs.listPacks().map((p) => {
+    const ab = p.kind === "ability" ? " ◆ability" : "";
+    const prov = p.kind === "ability" && p.learned_on
+      ? ` (learned on ${p.learned_on}${p.applied_on && p.applied_on.length ? `; applied on ${p.applied_on.join(", ")}` : ""})`
+      : "";
+    return `- ${p.dir}: ${p.name} — ${p.description}${p.tags.length ? ` [${p.tags.join(", ")}]` : ""}${ab}${prov}`;
+  }).join("\n") || "(none yet)";
 
   const entityIndex = entities.listEntities().map((e) =>
     `- ${e.slug}: ${e.name} (${e.type})${e.aliases.length ? ` aka ${e.aliases.join(", ")}` : ""} — ${e.description}`
   ).join("\n") || "(none yet)";
 
+  const lessonIndex = lessons.listLessons().map((l) =>
+    `- ${l.text}${l.src ? ` (src: ${l.src})` : ""}`
+  ).join("\n") || "(none yet)";
+
   return `You are the memory reviewer for a personal AI assistant. After each conversation turn you decide whether the assistant's long-term "context packs" and "entity notes" should change.
 
 A context pack is a living document about ONE topic (a project, a system, a recurring task, a domain). It has four sections:
@@ -72,12 +84,19 @@ An entity note is a short memory file about ONE specific named entity — a pers
 - Notes: current truth about the entity (who/what it is, role, preferences, relationships). Replaces wholesale.
 - Log: one-line dated observations, appended.
 
+An ABILITY is a special kind of pack (kind:"ability") for a REUSABLE HOW-TO that is NOT tied to one project — a procedure, pattern, or technique you would follow just as well on a different project later (e.g. "ship a mobile app: bump versionCode, build the APK, push the in-app updater"; "safely run a destructive DB write"; "wire up a new ArgoCD app"). A normal pack (kind:"context", the default) is about ONE project/system and stays scoped to it. Decide by NATURE, not by repetition: if THIS turn demonstrated a self-contained method you would re-run on a DIFFERENT project, capture it as an ability the FIRST time you see it — do not wait for it to recur. Give an ability an ACTIVITY-oriented name, description, and tags (what you DO — the verbs, tools, and artifacts involved) so it can be found later from a different project by the work being done, not by a project name. Set "learned_on" to the project pack dir this turn worked on and list that same dir in "applied_on". If an ability below (marked ◆ability) already covers the method, do NOT duplicate it — UPDATE it and add the current project dir to "applied_on" so it visibly transfers.
+
+A LESSON is a single always-loaded rule (NOT topic-gated like packs/entities — it loads on every turn). Lessons exist for ONE purpose: to stop a recurring mistake. Propose a lesson ONLY when THIS turn shows the assistant MISSED something it should already have known — i.e. the user corrected the assistant ("no", "that's wrong", "actually it's X"), or signalled repetition ("again", "I keep telling you", "as I said", "I've told you before", "like I mentioned"). That friction is the proof that topic-matched memory failed, so the corrected fact must move to the always-on tier. No correction/repetition signal in the turn → NO lesson (return an empty lessons array). A lesson is the CORRECT fact written as one crisp imperative line, cross-cutting and durable (a mechanism, rule, or constraint that will matter on future, possibly off-topic turns) — never a one-off task detail or a fact with no miss behind it. Point "src" at the pack that should hold the full context if one fits. If an existing lesson below already covers it, reuse its EXACT wording so it reinforces rather than duplicating.
+
 Existing packs:
 ${index}
 
 Known entities:
 ${entityIndex}
 
+Current lessons (always loaded):
+${lessonIndex}
+
 The turn to review:
 
 <user_message>
@@ -93,21 +112,26 @@ Decide. Rules:
 - UPDATE an existing pack when the turn touched that topic: append a journal line, and rewrite State if where-things-stand changed. Update Stance when the user expressed a lasting preference or rule; Procedure when a verified working method emerged.
 - PROMOTE durable conclusions out of the Journal. A confirmed root-cause diagnosis, an established fact, or a settled design decision must go into Stance/Procedure/State (the parts always injected in full), NOT only a Journal line — Journal is truncated to the last few lines on injection, so a conclusion left only there will silently fall out of recall over time.
 - CREATE a pack when the turn worked on a durable topic no existing pack covers. Topics recur more than you expect — a named system or project is durable by default. Do not create packs for one-off trivia, and prefer update when an existing pack fits.
+- ABILITY vs CONTEXT: most creates are context packs (a project/system tracker). Create an ability (kind:"ability") only for a genuinely reusable how-to as defined above, and always set learned_on + applied_on to the originating project dir. When a turn re-used an EXISTING ability on a NEW project, do NOT create anything — UPDATE that ability and put the new project dir in "applied_on" so the cross-project reuse is recorded.
 - Never store secrets, tokens, passwords, or credentials.
 - State should be concise (under 150 words). Journal entries one sentence. Never start a journal or log sentence with a date — dates are prepended automatically.
 - At most ${MAX_ACTIONS} pack actions.
 - Entities: add an item when the turn revealed something durable about a specific named person, place, project, org, or system — their role, status, preferences, or relationship to other work. Use the existing entity name when one matches (check aliases). Skip entities mentioned only in passing with nothing learned. Notes under 100 words; "notes" null means leave Notes unchanged. At most ${MAX_ENTITY_ACTIONS} entity items.
 - Packs and entities are independent — a turn can update both, either, or neither. Do not duplicate the same fact in a pack AND an entity unless it genuinely belongs to both.
+- Lessons are the rare case: at most ${MAX_LESSON_ACTIONS} per turn, and ONLY on a real correction/repetition signal as defined above. The default is an empty lessons array. When you do promote one, ALSO record the same fact in the appropriate pack (update/create) so the durable home stays authoritative — the lesson is just the always-on shortcut. Never put secrets in a lesson.
 
 Reply with ONLY a JSON object, no prose, no code fences:
 {"actions": [
-  {"action": "update", "pack": "<existing dir>", "journal": "<one sentence>", "state": "<full new State or null>", "stance": null, "procedure": null}
-  | {"action": "create", "dir": "<kebab-slug>", "name": "<title>", "description": "<one line: when this pack is relevant>", "tags": ["..."], "stance": "<or empty>", "procedure": "<or empty>", "state": "<where things stand>", "journal": "<one sentence>"}
+  {"action": "update", "pack": "<existing dir>", "journal": "<one sentence>", "state": "<full new State or null>", "stance": null, "procedure": null, "applied_on": ["<project dir, ONLY when this turn re-applied an existing ability to a new project>"]}
+  | {"action": "create", "dir": "<kebab-slug>", "name": "<title>", "description": "<one line: when this pack is relevant>", "tags": ["..."], "kind": "context|ability", "learned_on": "<originating project dir — abilities only>", "applied_on": ["<project dirs — abilities only>"], "stance": "<or empty>", "procedure": "<or empty>", "state": "<where things stand>", "journal": "<one sentence>"}
 ],
 "entities": [
   {"name": "<canonical name>", "type": "person|place|project|org|system|thing", "aliases": ["..."], "description": "<one line: who/what this is>", "notes": "<full new Notes or null>", "log": "<one sentence observation>"}
+],
+"lessons": [
+  {"text": "<the correct fact as one crisp imperative line>", "src": "<pack dir that holds the full context, or empty>", "trigger": "<the exact correction/repetition phrase from the turn>"}
 ]}
-or {"actions": [], "entities": []}`;
+or {"actions": [], "entities": [], "lessons": []}`;
 }
 
 function parseDecision(text) {
@@ -119,7 +143,8 @@ function parseDecision(text) {
     const obj = JSON.parse(raw.slice(start, end + 1));
     const actions = Array.isArray(obj.actions) ? obj.actions.slice(0, MAX_ACTIONS) : (obj.action ? [obj] : []);
     const entityActions = Array.isArray(obj.entities) ? obj.entities.slice(0, MAX_ENTITY_ACTIONS) : [];
-    return { actions, entities: entityActions };
+    const lessonActions = Array.isArray(obj.lessons) ? obj.lessons.slice(0, MAX_LESSON_ACTIONS) : [];
+    return { actions, entities: entityActions, lessons: lessonActions };
   } catch (e) {
     return null;
   }
@@ -154,12 +179,27 @@ function applyAction(a) {
       stance: typeof a.stance === "string" ? a.stance : "",
       procedure: typeof a.procedure === "string" ? a.procedure : "",
     }, "reviewer");
-    return { kind: "update", dir: a.pack, name: existing.name, note: a.journal || "state updated", protectedStance: !!r.protectedStance };
+    // Cross-project reuse: only abilities carry applied_on, so ignore the field
+    // on context packs (keeps project trackers churn-free).
+    let appliedTo = null;
+    if (existing.kind === "ability" && Array.isArray(a.applied_on)) {
+      for (const proj of a.applied_on.map((x) => String(x || "").trim()).filter(Boolean)) {
+        if (packs.recordApplied(a.pack, proj)) appliedTo = proj;
+      }
+    }
+    return { kind: "update", dir: a.pack, name: existing.name, note: a.journal || (appliedTo ? `reused on ${appliedTo}` : "state updated"), protectedStance: !!r.protectedStance, appliedTo };
   }
   if (a.action === "create" && (a.dir || a.name)) {
     const dir = packs.slugify(a.dir || a.name);
+    const kind = a.kind === "ability" ? "ability" : "context";
+    const learned_on = String(a.learned_on || "").trim();
+    const applied_on = Array.isArray(a.applied_on)
+      ? a.applied_on.map((x) => String(x || "").trim()).filter(Boolean)
+      : [];
+    const projects = applied_on.length ? applied_on : (learned_on ? [learned_on] : []);
     if (packs.readPack(dir)) {
       packs.updatePack(dir, { journal: a.journal || "", state: a.state || "" }, "reviewer");
+      if (kind === "ability") for (const proj of projects) packs.recordApplied(dir, proj);
       return { kind: "update", dir, name: a.name || dir, note: a.journal || "state updated" };
     }
     const pack = packs.createPack({
@@ -171,8 +211,11 @@ function applyAction(a) {
       procedure: a.procedure || "",
       state: a.state || "",
       journal: a.journal || "",
+      kind,
+      learned_on: kind === "ability" ? learned_on : "",
+      applied_on: kind === "ability" ? projects : [],
     }, "reviewer");
-    return { kind: "create", dir: pack.dir, name: pack.name, note: a.description || "" };
+    return { kind: "create", dir: pack.dir, name: pack.name, note: a.description || "", ability: kind === "ability", learned_on: pack.learned_on };
   }
   return null;
 }
@@ -190,6 +233,25 @@ function applyEntityAction(e) {
   return { kind: created ? "create" : "update", slug: entity.slug, name: entity.name, type: entity.type, note: e.log || e.description || "" };
 }
 
+function applyLessonAction(l) {
+  if (!l || typeof l !== "object") return null;
+  const text = String(l.text || "").trim();
+  if (!text) return null;
+  // Structural enforcement of "promote only after a miss": the model must
+  // cite the in-turn correction/repetition phrase. No trigger → no lesson,
+  // regardless of what the model decided.
+  if (!String(l.trigger || "").trim()) return null;
+  const guard = packGuard.scanForInjection(text, { strict: true });
+  if (guard.flagged) {
+    console.warn(`[pack-review] guard blocked lesson (${guard.kind}): ${guard.evidence || text.slice(0, 60)}`);
+    return { kind: "skipped", reason: guard.kind };
+  }
+  const r = lessons.addLesson({ text, src: String(l.src || "").trim(), origin: "reviewer" });
+  if (r.added) return { kind: "create", id: r.id, text, overCap: !!r.overCap };
+  if (r.reinforced) return { kind: "reinforce", id: r.id, text };
+  return { kind: "skipped", reason: r.reason || "not added" };
+}
+
 // Fire-and-forget. `announce` is an async (text) => void bound to the
 // originating channel; failures are logged, never thrown into the turn.
 function reviewTurn({ userText, assistantText, channelId, announce }) {
@@ -206,17 +268,19 @@ function reviewTurn({ userText, assistantText, channelId, announce }) {
     systemPrompt: "You are a background memory reviewer. Reply with ONLY the requested JSON object. No prose, no markdown, no tool use.",
   }).then(({ text }) => {
     const decision = parseDecision(text);
-    if (!decision || (decision.actions.length === 0 && decision.entities.length === 0)) return;
+    if (!decision || (decision.actions.length === 0 && decision.entities.length === 0 && (decision.lessons || []).length === 0)) return;
     const lines = [];
     for (const a of decision.actions) {
       try {
         const r = applyAction(a);
         if (r && r.kind === "skipped") {
           lines.push(`🛡️ Skipped a memory write that looked like an injected instruction (${r.reason}).`);
+        } else if (r && r.kind === "create" && r.ability) {
+          lines.push(`🧩 New ability: ${r.name}${r.learned_on ? ` (learned on ${r.learned_on})` : ""}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
+        } else if (r && r.kind === "create") {
+          lines.push(`📦 New pack: ${r.name}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
         } else if (r) {
-          lines.push(r.kind === "create"
-            ? `📦 New pack: ${r.name}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`
-            : `✏️ ${r.name} — ${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
+          lines.push(`✏️ ${r.name} — ${clipWords(r.note, 180)}${r.appliedTo ? ` 🧩 (now also applies to ${r.appliedTo})` : ""}\n↳ open-claudia pack show ${r.dir}`);
         }
       } catch (e) {
         console.warn(`[pack-review] apply failed: ${e.message}`);
@@ -235,6 +299,23 @@ function reviewTurn({ userText, assistantText, channelId, announce }) {
         console.warn(`[pack-review] entity apply failed: ${e.message}`);
       }
     }
+    for (const la of (decision.lessons || [])) {
+      try {
+        const r = applyLessonAction(la);
+        if (!r) continue;
+        if (r.kind === "skipped") {
+          if (r.reason && /exfil|override|base64/.test(r.reason)) {
+            lines.push(`🛡️ Skipped a lesson that looked like an injected instruction (${r.reason}).`);
+          }
+        } else if (r.kind === "create") {
+          lines.push(`📌 New lesson — I got this wrong before, so I'll always keep it loaded now:\n"${clipWords(r.text, 200)}"${r.overCap ? "\n(That's over the lessons cap — the nightly dream will tidy.)" : ""}`);
+        } else if (r.kind === "reinforce") {
+          lines.push(`📌 Reinforced a lesson I keep needing — clearly worth keeping front of mind:\n"${clipWords(r.text, 200)}"`);
+        }
+      } catch (e) {
+        console.warn(`[pack-review] lesson apply failed: ${e.message}`);
+      }
+    }
     if (lines.length > 0 && typeof announce === "function") {
       announce(formatAnnouncement(lines)).catch(() => {});
     }
@@ -243,4 +324,4 @@ function reviewTurn({ userText, assistantText, channelId, announce }) {
   });
 }
 
-module.exports = { reviewTurn, parseDecision, applyAction, applyEntityAction, buildReviewPrompt, clipWords, ENTITY_EMOJI };
+module.exports = { reviewTurn, parseDecision, applyAction, applyEntityAction, applyLessonAction, buildReviewPrompt, clipWords, ENTITY_EMOJI };

package/core/packs.js

@@ -66,6 +66,10 @@ function serialize(pack) {
     `tags: ${(pack.tags || []).join(", ")}`,
   ];
   if (pack.parent) fmLines.push(`parent: ${pack.parent}`);
+  if (pack.skill) fmLines.push("skill: true");
+  if (pack.kind && pack.kind !== "context") fmLines.push(`kind: ${pack.kind}`);
+  if (pack.learned_on) fmLines.push(`learned_on: ${pack.learned_on}`);
+  if (Array.isArray(pack.applied_on) && pack.applied_on.length) fmLines.push(`applied_on: ${pack.applied_on.join(", ")}`);
   fmLines.push(
     `created: ${pack.created || new Date().toISOString()}`,
     `updated: ${pack.updated || new Date().toISOString()}`,
@@ -98,6 +102,10 @@ function readPack(dir) {
     description: fm.description || "",
     tags: (fm.tags || "").split(",").map((t) => t.trim()).filter(Boolean),
     parent: fm.parent || null,
+    skill: fm.skill === "true" || fm.skill === true,
+    kind: fm.kind || "context",
+    learned_on: fm.learned_on || "",
+    applied_on: (fm.applied_on || "").split(",").map((t) => t.trim()).filter(Boolean),
     created: fm.created || "",
     updated: fm.updated || (stat ? stat.mtime.toISOString() : ""),
     last_used: fm.last_used || "",
@@ -128,6 +136,83 @@ function findPack(nameOrDir) {
   return listPacks().find((p) => p.dir.toLowerCase() === needle || p.name.toLowerCase() === needle) || null;
 }
 
+// Packs explicitly flagged as reusable how-tos. These get an always-on
+// Tier-1 index in the system prompt (name + description), so the agent knows
+// the skill exists and can load its Procedure on demand. Most packs are
+// project trackers, not skills — so this is opt-in, not "any pack with a
+// Procedure".
+function listSkillPacks() {
+  return listPacks().filter((p) => p.skill && !p.archived);
+}
+
+function setSkill(nameOrDir, on) {
+  const pack = findPack(nameOrDir);
+  if (!pack) return null;
+  pack.skill = !!on;
+  if (on && pack.kind !== "ability") pack.kind = "ability";
+  pack.updated = new Date().toISOString();
+  writePack(pack);
+  return pack;
+}
+
+// Reusable abilities (how-tos / patterns / themes) — kind:"ability". These are
+// the nodes that transfer across projects via governed-by edges, and the pool
+// the always-on skill index is promoted from. Project trackers are kind:"context".
+function listAbilities() {
+  return listPacks().filter((p) => p.kind === "ability" && !p.archived);
+}
+
+function setKind(nameOrDir, kind) {
+  const pack = findPack(nameOrDir);
+  if (!pack) return null;
+  pack.kind = String(kind || "context").trim() || "context";
+  pack.updated = new Date().toISOString();
+  writePack(pack);
+  return pack;
+}
+
+// Record that an ability was applied on a project (provenance of reuse): appends
+// to applied_on (deduped) and sets learned_on to the first project if unset.
+function recordApplied(nameOrDir, project) {
+  const pack = findPack(nameOrDir);
+  if (!pack || !project) return null;
+  const proj = String(project).trim();
+  if (!proj) return pack;
+  if (!pack.learned_on) pack.learned_on = proj;
+  const set = new Set(pack.applied_on || []);
+  set.add(proj);
+  pack.applied_on = [...set];
+  pack.updated = new Date().toISOString();
+  writePack(pack);
+  return pack;
+}
+
+// Close the learning loop from actual USE. Given the node ids the agent opened
+// together in one turn (pack:<dir> / entity:<slug>), treat every ability opened
+// alongside a project (context) pack as "this ability was applied while working
+// on that project" and record it. applied_on growing is what forms the
+// project→ability governed-by edge on the next structural sync, so reuse
+// transfers automatically from real use. Returns the pairs NEWLY transferred
+// (for a one-line "it transfers there now too" announcement).
+function recordCoUse(openedIds) {
+  const opened = [...new Set(openedIds || [])]
+    .filter((id) => typeof id === "string" && id.startsWith("pack:"))
+    .map((id) => readPack(id.slice(5)))
+    .filter(Boolean);
+  const abilities = opened.filter((p) => p.kind === "ability");
+  const contexts = opened.filter((p) => p.kind !== "ability");
+  const transferred = [];
+  for (const ab of abilities) {
+    for (const ctx of contexts) {
+      if (ab.dir === ctx.dir) continue;
+      const isNew = !(ab.applied_on || []).includes(ctx.dir);
+      recordApplied(ab.dir, ctx.dir);
+      if (isNew) transferred.push({ ability: ab.dir, abilityName: ab.name, project: ctx.dir, projectName: ctx.name });
+    }
+  }
+  return transferred;
+}
+
 function writePack(pack) {
   ensureDir();
   const dir = path.join(PACKS_DIR, pack.dir);
@@ -137,7 +222,7 @@ function writePack(pack) {
   return pack.dir;
 }
 
-function createPack({ dir, name, description, tags, stance, procedure, state, journal, parent }, origin = "user") {
+function createPack({ dir, name, description, tags, stance, procedure, state, journal, parent, skill, kind, learned_on, applied_on }, origin = "user") {
   const d = slugify(dir || name);
   if (!d) throw new Error("pack needs a name");
   if (readPack(d)) throw new Error(`pack ${d} already exists`);
@@ -147,6 +232,10 @@ function createPack({ dir, name, description, tags, stance, procedure, state, jo
     description: description || "",
     tags: Array.isArray(tags) ? tags : [],
     parent: parent || null,
+    skill: !!skill,
+    kind: kind || "context",
+    learned_on: learned_on || "",
+    applied_on: Array.isArray(applied_on) ? applied_on : [],
     created: new Date().toISOString(),
     sections: {
       Stance: stance || "",
@@ -227,12 +316,15 @@ function recordForegroundWrite(dir, { tool, oldString, content } = {}) {
 
 // Apply a reviewer mutation. Only supplied fields change; journal entries
 // append (capped); state replaces (it represents "current truth").
-function updatePack(dir, { description, tags, stance, procedure, state, journal } = {}, origin = "user") {
+function updatePack(dir, { description, tags, stance, procedure, state, journal, skill, kind, learned_on } = {}, origin = "user") {
   const pack = readPack(dir);
   if (!pack) throw new Error(`no pack: ${dir}`);
   pack.updated = new Date().toISOString();
   if (description) pack.description = description;
   if (Array.isArray(tags) && tags.length) pack.tags = tags;
+  if (typeof skill === "boolean") pack.skill = skill;
+  if (typeof kind === "string" && kind.trim()) pack.kind = kind.trim();
+  if (typeof learned_on === "string" && learned_on.trim()) pack.learned_on = learned_on.trim();
   const applied = [];
   let protectedStance = false;
   if (typeof stance === "string" && stance.trim()) {
@@ -470,6 +562,7 @@ function matchPacks(text, { limit = 3, threshold = null } = {}) {
 module.exports = {
   PACKS_DIR, SECTIONS, slugify,
   listPacks, findPack, readPack, writePack, createPack, updatePack, removePack,
+  listSkillPacks, setSkill, listAbilities, setKind, recordApplied, recordCoUse,
   touchUsed, packNameFromPath, matchPacks, reindex, markIndexDirty,
   archivePack, restorePack, listArchived,
   readProvenance, provenanceOf, setProvenance, recordForegroundWrite,