kenaz 0.3.11 → 0.3.13

package/core/.specialist/tools/lessons-harvest.js

@@ -0,0 +1,243 @@
+'use strict';
+/**
+ * Self-improvement from the project's own history (TASK_2427). Read-only suggestions: nothing here writes a lesson.
+ *   harvest   history items not yet recorded, each with a ready `kenaz learn add ... --source harvest:<id>`
+ *             (a) rework: a card's branch got commits after the agent's delivery, or a fix-up after the merge
+ *             (b) failed verification: executor result files with ok=false; cards moved to blocked with a reason
+ *             (c) handoffs: bullets under the A (Assessment) section's unverified / risk lines
+ *   metrics   first-pass merge rate per rigor vs the current `kenaz subagent` model; the 3 files with most rework commits
+ *   selfStats numbers for `kenaz stats` section Self-improvement (benefit measurement, DESIGN.md decision rule)
+ * Recorded items live in <project>/.kenaz/knowledge/.harvested.json {id: iso time}; items older than 30 days age out.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const yaml = require('../../.vendor/require-yaml.cjs');
+
+const DAY = 24 * 60 * 60 * 1000;
+const WINDOW_DAYS = 30;
+// Harvested items ask Ansuz for the why; weeks later nobody remembers it (measured 2026-10-11: a 30-day
+// window listed 27 items in this repo, mostly cards nobody had context on any more). Metrics keep 30 days.
+const HARVEST_DAYS = 7;
+const LIST_MAX = 10;
+const NUDGE_CONVERSION_MS = 15 * 60 * 1000;
+const MAX_PATHS = 6;
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const RIGORS = ['low', 'medium', 'high'];
+const SUGGEST_BELOW = 0.7;
+const MIN_CARDS = 3;
+
+const root = (p) => path.resolve(p || process.cwd());
+const harvestedFile = (p) => path.join(root(p), '.kenaz', 'knowledge', '.harvested.json');
+const cacheFile = (p) => path.join(root(p), '.kenaz', 'specialist', 'harvest-cache.json');
+const nudgeLog = (p) => path.join(root(p), '.kenaz', 'specialist', 'correction-nudges.jsonl');
+const norm = (s) => String(s).replace(/\\/g, '/');
+const one = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+
+function readHarvested(p) {
+  try { return JSON.parse(fs.readFileSync(harvestedFile(p), 'utf8')) || {}; } catch (_) { return {}; }
+}
+
+/** Record an item as harvested (called by `learn add --source harvest:<id>`); drops the banner cache. */
+function markHarvested(p, id, now = Date.now()) {
+  const state = readHarvested(p);
+  state[id] = new Date(now).toISOString();
+  fs.mkdirSync(path.dirname(harvestedFile(p)), { recursive: true });
+  fs.writeFileSync(harvestedFile(p), JSON.stringify(state, null, 2) + '\n');
+  try { fs.unlinkSync(cacheFile(p)); } catch (_) { /* none */ }
+}
+
+const stats = () => require('../../.formation/tools/kenaz-stats.js');
+
+/** Files a commit touched, minus Kenaz bookkeeping. */
+function commitFiles(repo, sha) {
+  try {
+    return stats().git(repo, 'show', '--name-only', '--format=', sha).split('\n').map(norm).filter((f) => f && !f.startsWith('.kenaz/'));
+  } catch (_) { return []; }
+}
+
+/** (a) every rework card of the window with the files its extra commits touched (reuses kenaz-stats' detection). */
+function reworkItems(repo, now, days) {
+  const d = stats().dispatchStats({ repo, now, days });
+  return (d.rework || []).map((r) => {
+    const perCommit = (r.shas || []).map((sha) => commitFiles(repo, sha));
+    return { card: r.card, why: r.why, perCommit, files: [...new Set(perCommit.flat())] };
+  });
+}
+
+const cardFiles = (repo) => {
+  const out = [];
+  for (const base of [path.join(repo, '.kenaz', 'tasks'), path.join(repo, '.collaboration', 'tasks')]) {
+    if (!fs.existsSync(base)) continue;
+    for (const st of fs.readdirSync(base)) {
+      let names = []; try { names = fs.readdirSync(path.join(base, st)); } catch (_) { continue; }
+      for (const n of names) if (/^TASK_\d+.*\.ya?ml$/i.test(n)) out.push({ status: st, file: path.join(base, st, n), id: /^(TASK_\d+)/i.exec(n)[1].toUpperCase() });
+    }
+    return out; // .kenaz/tasks wins, as task-api does
+  }
+  return out;
+};
+
+function readCard(file) { try { return yaml.load(fs.readFileSync(file, 'utf8')) || {}; } catch (_) { return {}; } }
+
+/** (b) cards in blocked/ with a reason, moved in the window. */
+function blockedItems(repo, now, days) {
+  const out = [];
+  for (const c of cardFiles(repo).filter((x) => x.status === 'blocked')) {
+    if (now - fs.statSync(c.file).mtimeMs > days * DAY) continue;
+    const card = readCard(c.file);
+    const reason = one(card.blocked_reason || card.block_reason || card.blocker || card.blocked_by || card.reason);
+    if (!reason) continue;
+    out.push({ id: `blocked:${c.id}`, type: 'fact', paths: [].concat(card.scope_paths || []).map(norm), why: `${c.id} was blocked: ${reason.slice(0, 160)}` });
+  }
+  return out;
+}
+
+/** (b) executor result files (bifrost/exec.js, written under <tmp>/kenaz-exec by dispatch.js) with ok=false for this project. */
+function execItems(repo, now, days, execDir) {
+  const dir = execDir || path.join(os.tmpdir(), 'kenaz-exec');
+  let names = []; try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.result.json')); } catch (_) { return []; }
+  const me = norm(root(repo)).toLowerCase();
+  const out = [];
+  for (const n of names) {
+    const file = path.join(dir, n);
+    let r; try { if (now - fs.statSync(file).mtimeMs > days * DAY) continue; r = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { continue; }
+    if (!r || r.ok !== false) continue;
+    const wt = norm(r.worktree || '').toLowerCase();
+    if (!(wt.startsWith(me + '/') || wt.includes('/' + path.basename(me) + '/'))) continue;
+    const stem = n.replace(/\.result\.json$/, '');
+    out.push({ id: `exec:${stem}`, type: 'check', paths: [], why: `${r.adapter || 'executor'} ${r.model || ''} run ${stem.split('-')[0]} failed: ${one(r.error || `exit ${r.exitCode}`)}`.replace(/\s+/g, ' ') });
+  }
+  return out;
+}
+
+/** (c) lines under "## A" of recent handoffs that are unverified / risk bullets. */
+function handoffItems(repo, now, days) {
+  const dir = path.join(root(repo), '.kenaz', 'handoffs');
+  let names = []; try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')); } catch (_) { return []; }
+  const out = [];
+  for (const n of names) {
+    const file = path.join(dir, n);
+    if (now - fs.statSync(file).mtimeMs > days * DAY) continue;
+    let inA = false, inRisk = false;
+    for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+      if (/^##\s/.test(line)) { inA = /^##\s*A\b/.test(line); inRisk = false; continue; }
+      if (!inA) continue;
+      const top = /^[-*]\s+(.*)$/.exec(line);
+      const sub = /^\s+[-*]\s+(.*)$/.exec(line);
+      let text = null;
+      if (top) {
+        inRisk = /未驗證|風險|unverified|risk/i.test(top[1]);
+        if (inRisk) text = top[1].replace(/^[^：:]*[：:]\s*/, '');
+      } else if (sub && inRisk) text = sub[1];
+      text = one(text);
+      if (!text) continue;
+      const id = `handoff:${n.replace(/\.md$/, '')}:${crypto.createHash('sha1').update(text).digest('hex').slice(0, 6)}`;
+      out.push({ id, type: 'fact', paths: [], why: `handoff ${n.slice(0, 16)}: ${text.slice(0, 200)}` });
+    }
+  }
+  return out;
+}
+
+/** Items from the last 30 days not yet recorded, each with the ready command. Empty on any failure. */
+function harvest({ projectPath, now = Date.now(), days = HARVEST_DAYS, execDir } = {}) {
+  const repo = root(projectPath);
+  const done = readHarvested(repo);
+  const safe = (fn) => { try { return fn(); } catch (_) { return []; } };
+  const items = [
+    ...safe(() => reworkItems(repo, now, days)).map((r) => ({ id: `rework:${r.card}`, type: 'check', paths: r.files, why: `${r.card} needed rework: ${r.why}` })),
+    ...safe(() => execItems(repo, now, days, execDir)),
+    ...safe(() => blockedItems(repo, now, days)),
+    ...safe(() => handoffItems(repo, now, days)),
+  ].filter((i) => !done[i.id]);
+  return items.map((i) => ({ ...i, cmd: `kenaz learn add --scope project --type ${i.type}${i.paths.length ? ` --paths ${i.paths.slice(0, MAX_PATHS).join(',')}` : ''} --text "<why: ${i.why.replace(/"/g, "'").slice(0, 120)}>" --source harvest:${i.id}` }));
+}
+
+function writeCount(projectPath, now = Date.now()) {
+  const n = harvest({ projectPath, now }).length;
+  try { fs.mkdirSync(path.dirname(cacheFile(projectPath)), { recursive: true }); fs.writeFileSync(cacheFile(projectPath), JSON.stringify({ t: now, n })); } catch (_) { /* optional */ }
+  return n;
+}
+
+/** Open item count for the boot banner. Boot never waits for the git scan (7 s cold in this repo): a missing
+ *  or stale cache starts a detached refresh and the banner uses what it has (nothing on the very first boot).
+ *  o.sync computes in-process (tests, `kenaz learn review`); o.refresh replaces the detached spawn (tests). */
+function openCount(projectPath, now = Date.now(), o = {}) {
+  let c = null;
+  try { c = JSON.parse(fs.readFileSync(cacheFile(projectPath), 'utf8')); } catch (_) { /* no cache */ }
+  if (c && now - c.t < CACHE_TTL_MS) return c.n;
+  if (o.sync) return writeCount(projectPath, now);
+  (o.refresh || ((p) => require('child_process').spawn(process.execPath, [__filename, '--refresh-cache', p], { detached: true, stdio: 'ignore', windowsHide: true }).unref()))(projectPath);
+  return c ? c.n : 0;
+}
+
+/** Suggestions only: per-rigor first-pass rate with the model in use, and the 3 files with most rework commits. */
+function metrics({ projectPath, now = Date.now(), days = WINDOW_DAYS } = {}) {
+  const repo = root(projectPath);
+  const out = [];
+  try {
+    const d = stats().dispatchStats({ repo, now, days });
+    const rigorOf = {};
+    for (const c of cardFiles(repo)) rigorOf[c.id] = RIGORS.includes(readCard(c.file).rigor) ? readCard(c.file).rigor : 'medium';
+    const rework = new Set((d.rework || []).map((r) => r.card));
+    let models = {};
+    try { for (const r of require('../../.formation/tools/dispatch-model.js').describe(repo).rows) models[r.rigor] = r.model; } catch (_) { /* model unknown */ }
+    for (const rigor of RIGORS) {
+      const cards = (d.mergedCards || []).filter((c) => (rigorOf[c] || 'medium') === rigor);
+      const pass = cards.filter((c) => !rework.has(c)).length;
+      if (cards.length >= MIN_CARDS && pass / cards.length < SUGGEST_BELOW) {
+        out.push(`${rigor}: ${pass}/${cards.length} first-pass${models[rigor] ? ` with ${models[rigor]}` : ''}; consider kenaz subagent set <stronger model> --rigor ${rigor}`);
+      }
+    }
+    const perFile = {};
+    for (const r of reworkItems(repo, now, days)) for (const files of r.perCommit) for (const f of files) perFile[f] = (perFile[f] || 0) + 1;
+    const top = Object.entries(perFile).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 3);
+    if (top.length) out.push(`most rework commits: ${top.map(([f, n]) => `${f} (${n})`).join(', ')}`);
+  } catch (_) { /* no git history: no suggestions */ }
+  return out;
+}
+
+function print(items, suggestions, out) {
+  if (items.length) out(`History items to review (${items.length}); for each, fill in the why and run the command, or ignore it:`);
+  for (const i of items.slice(0, LIST_MAX)) { out(`  ${i.id}: ${i.why}`); out(`    ${i.cmd}`); }
+  if (items.length > LIST_MAX) out(`  ... ${items.length - LIST_MAX} more (oldest); record the newest first, while the context is fresh`);
+  if (suggestions.length) out('Project metric suggestions (not applied):');
+  for (const s of suggestions) out(`  ${s}`);
+}
+
+/** Numbers for `kenaz stats` section Self-improvement. lessons.js is required lazily (it requires this file). */
+function selfStats({ projectPath, home, now = Date.now(), days = 14 }) {
+  const L = require('./lessons.js');
+  const since = now - days * DAY;
+  const jl = (f) => { try { return fs.readFileSync(f, 'utf8').split('\n').map((l) => { try { return JSON.parse(l); } catch (_) { return null; } }).filter(Boolean); } catch (_) { return []; } };
+  const nudges = jl(nudgeLog(projectPath)).map((r) => Date.parse(r.ts)).filter((t) => t >= since);
+  const records = []; // lesson-recording moments: a new lesson or a recurrence
+  const bySource = {};
+  let graduated = 0;
+  for (const scope of ['project', 'user']) {
+    const rec = jl(L.usageLog(scope, projectPath, home)).filter((r) => r.kind === 'recurrence');
+    const uses = L.readUses(L.usageLog(scope, projectPath, home));
+    for (const r of rec) records.push(Date.parse(r.ts));
+    for (const l of L.everLessons(scope, { projectPath, home })) {
+      if (l.created) records.push(l.created);
+      if (l.graduated) graduated++;
+      const key = String(l.source || 'manual').split(':')[0];
+      const s = bySource[key] || (bySource[key] = { lessons: 0, fired: 0, recurBefore: 0, recurAfter: 0 });
+      const u = uses[`${l.id}.md`];
+      const firstFire = u && u.times.length ? Math.min(...u.times) : null;
+      s.lessons++; if (u && u.fires) s.fired++;
+      for (const r of rec.filter((x) => x.file === `${l.id}.md`)) {
+        if (firstFire != null && Date.parse(r.ts) > firstFire) s.recurAfter++; else s.recurBefore++;
+      }
+    }
+  }
+  const converted = nudges.filter((t) => records.some((r) => r >= t && r - t <= NUDGE_CONVERSION_MS)).length;
+  const open = harvest({ projectPath, now }).length;
+  const recorded = Object.values(readHarvested(projectPath)).filter((t) => Date.parse(t) >= since).length;
+  return { nudges: nudges.length, converted, bySource, graduated, harvestOpen: open, harvestRecorded: recorded };
+}
+
+if (require.main === module && process.argv[2] === '--refresh-cache') { try { writeCount(process.argv[3]); } catch (_) { /* best effort */ } }
+
+module.exports = { HARVEST_DAYS, harvest, markHarvested, readHarvested, openCount, metrics, print, selfStats, reworkItems, WINDOW_DAYS };

package/core/.specialist/tools/lessons-lifecycle.js

@@ -0,0 +1,103 @@
+'use strict';
+/**
+ * Lesson lifecycle helpers (TASK_2425): active -> graduated into code | merged | archived.
+ * Pure similarity/candidate logic plus frontmatter edits and moves into <layer>/archive/<kind>/.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DAY = 24 * 60 * 60 * 1000;
+const MAX_ACTIVE_PER_LAYER = 20;
+const NEAR_CAP = 18;
+// Overlap coefficient, not Jaccard: a re-learned lesson is usually a shorter or longer paraphrase. Measured
+// 2026-10-11 (8 paraphrase pairs vs 6328 pairs of distinct memory descriptions): Jaccard >= 0.6 caught 1/8,
+// overlap >= 0.45 caught 5/8 with 0 false merges (the distinct pairs peak at 0.42).
+const SIMILAR_MIN = 0.45;
+const GRADUATE_FIRES = 3;
+const GRADUATE_RECURRENCES = 2;
+const PREF_REVIEW_AFTER_MS = 90 * DAY;
+const WINDOW_MS = 30 * DAY;
+
+/** Latin/digit words plus every CJK character as its own token. */
+function tokens(text) {
+  return new Set(String(text).toLowerCase().match(/[a-z0-9_]+|[぀-ヿ㐀-鿿豈-﫿가-힯]/g) || []);
+}
+
+/** Shared tokens over the smaller set: 1 when one text contains the other. */
+function overlap(a, b) {
+  const x = tokens(a), y = tokens(b);
+  if (!x.size || !y.size) return 0;
+  let inter = 0;
+  for (const t of x) if (y.has(t)) inter++;
+  return inter / Math.min(x.size, y.size);
+}
+
+/** All pairs of lessons, most similar first: [{a, b, score}]. */
+function similarPairs(rows) {
+  const out = [];
+  for (let i = 0; i < rows.length; i++) {
+    for (let j = i + 1; j < rows.length; j++) out.push({ a: rows[i], b: rows[j], score: overlap(rows[i].text, rows[j].text) });
+  }
+  return out.sort((p, q) => q.score - p.score);
+}
+
+function findSimilar(rows, text) {
+  let best = null;
+  for (const l of rows) {
+    const score = overlap(l.text, text);
+    if (score >= SIMILAR_MIN && (!best || score > best.score)) best = { lesson: l, score };
+  }
+  return best && best.lesson;
+}
+
+/** Set or add top-level frontmatter keys in place (strings are JSON-quoted). */
+function setFm(file, kv) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const m = raw.match(/^---(\r?\n)([\s\S]*?)(\r?\n)---/);
+  if (!m) throw new Error(`${file} has no frontmatter`);
+  let body = m[2];
+  for (const [k, v] of Object.entries(kv)) {
+    const line = `${k}: ${typeof v === 'number' ? v : JSON.stringify(v)}`;
+    const re = new RegExp(`^${k}:.*$`, 'm');
+    body = re.test(body) ? body.replace(re, () => line) : `${body}${m[3]}${line}`;
+  }
+  fs.writeFileSync(file, `---${m[1]}${body}${m[3]}---${raw.slice(m[0].length)}`);
+}
+
+function bumpRecurrence(l, now = Date.now()) {
+  const n = (l.recurrences || 0) + 1;
+  setFm(l.file, { recurrences: n, last_recurrence: new Date(now).toISOString() });
+  return n;
+}
+
+/** Move a lesson to <layer>/archive/<kind>/ after stamping `extra` into its frontmatter. */
+function archiveTo(l, kind, extra) {
+  setFm(l.file, extra);
+  const dir = path.join(path.dirname(l.file), 'archive', kind);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.renameSync(l.file, path.join(dir, path.basename(l.file)));
+}
+
+const isCandidate = (l) => (l.recent || 0) >= GRADUATE_FIRES || (l.recurrences || 0) >= GRADUATE_RECURRENCES;
+
+/** What `kenaz learn review` shows: graduation candidates, prefs due for confirmation, merge pairs, Kenaz-product lessons. */
+function review(layers, now = Date.now()) {
+  const all = layers.flat();
+  return {
+    candidates: all.filter(isCandidate),
+    oldPrefs: all.filter((l) => l.type === 'pref' && l.created && now - l.created > PREF_REVIEW_AFTER_MS),
+    pairs: layers.flatMap((rows) => similarPairs(rows)).filter((p) => p.score >= SIMILAR_MIN),
+    aboutKenaz: all.filter((l) => l.about === 'kenaz'),
+  };
+}
+
+/** Lines for the boot banner, empty when nothing needs action. */
+function bannerNotice(layers, harvestOpen = 0) {
+  const toGraduate = layers.flat().filter(isCandidate).length;
+  const nearCap = layers.filter((rows) => rows.length >= NEAR_CAP).length;
+  if (toGraduate || nearCap) return [`[lessons] ${toGraduate} to graduate, ${nearCap} near cap${harvestOpen ? `, ${harvestOpen} history items` : ''}: kenaz learn review`];
+  return harvestOpen ? [`[learn] ${harvestOpen} history items to review: kenaz learn review`] : [];
+}
+
+module.exports = { tokens, overlap, similarPairs, findSimilar, setFm, bumpRecurrence, archiveTo, isCandidate, review, bannerNotice,
+  MAX_ACTIVE_PER_LAYER, NEAR_CAP, SIMILAR_MIN, WINDOW_MS, DAY };

package/core/.specialist/tools/lessons.js

@@ -23,6 +23,8 @@ const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const yaml = require('../../.vendor/require-yaml.cjs');
+const lc = require('./lessons-lifecycle');
+const hv = require('./lessons-harvest');
 
 const DAY = 24 * 60 * 60 * 1000;
 const ARCHIVE_AFTER_MS = 30 * DAY;
@@ -31,6 +33,8 @@ const INJECT_MAX_LINES = 5;
 const INJECT_MAX_BYTES = 600;
 const MAX_UNRELATED_FIRE_RATE = 0.2;
 const MIN_REPLAY_CALLS = 20;
+const BANNER_PREFS = 10;
+const DAY_MS = lc.DAY;
 
 const homeDir = () => process.env.HOME || process.env.USERPROFILE || os.homedir();
 const userDir = (home) => path.join(home || homeDir(), '.kenaz', 'knowledge');
@@ -48,7 +52,7 @@ function readLesson(file) {
     if (!fm || typeof fm.name !== 'string' || !fm.name.startsWith('lesson-')) return null;
     return { id: fm.name, file, type: fm.type, scope: fm.scope, created: Date.parse(fm.created) || 0,
       triggers: Array.isArray(fm.triggers) ? fm.triggers : [], paths: Array.isArray(fm.paths) ? fm.paths : [],
-      symptom: fm.symptom || null, text: (m[2] || '').trim() };
+      symptom: fm.symptom || null, source: fm.source || null, graduated: !!fm.graduated_to, about: fm.about || null, recurrences: Number(fm.recurrences) || 0, carried: Number(fm.fires) || 0, text: (m[2] || '').trim() };
   } catch (_) { return null; }
 }
 
@@ -59,8 +63,9 @@ function readUses(log) {
   for (const line of raw.split('\n')) {
     let r; try { r = JSON.parse(line); } catch (_) { continue; }
     if (!r || (r.kind !== 'guard' && r.kind !== 'inject') || !r.file) continue;
-    const u = uses[r.file] || (uses[r.file] = { fires: 0, last: 0 });
-    u.fires++; u.last = Math.max(u.last, Date.parse(r.ts) || 0);
+    const u = uses[r.file] || (uses[r.file] = { fires: 0, last: 0, times: [] });
+    const t = Date.parse(r.ts) || 0;
+    u.fires++; u.last = Math.max(u.last, t); u.times.push(t);
   }
   return uses;
 }
@@ -74,7 +79,7 @@ function logUse(scope, p, home, id, kind) {
 }
 
 /** Active lessons of one layer with fire stats; moves lessons idle > 30 days to archive/ first. */
-function listLayer(scope, { projectPath, home, now = Date.now() } = {}) {
+function listLayer(scope, { projectPath, home, now = Date.now(), readOnly = false } = {}) {
   const dir = layerDir(scope, projectPath, home);
   let names = [];
   try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')); } catch (_) { return []; }
@@ -83,9 +88,10 @@ function listLayer(scope, { projectPath, home, now = Date.now() } = {}) {
   for (const n of names) {
     const l = readLesson(path.join(dir, n));
     if (!l) continue;
-    const u = uses[n] || { fires: 0, last: 0 };
-    l.scope = scope; l.fires = u.fires; l.lastFired = u.last || null;
-    if (l.type !== 'pref' && now - Math.max(u.last, l.created) > ARCHIVE_AFTER_MS) {
+    const u = uses[n] || { fires: 0, last: 0, times: [] };
+    l.scope = scope; l.fires = u.fires + l.carried; l.lastFired = u.last || null;
+    l.recent = u.times.filter((t) => now - t <= lc.WINDOW_MS).length;
+    if (!readOnly && l.type !== 'pref' && now - Math.max(u.last, l.created) > ARCHIVE_AFTER_MS) {
       fs.mkdirSync(path.join(dir, 'archive'), { recursive: true });
       fs.renameSync(l.file, path.join(dir, 'archive', n));
       continue;
@@ -95,6 +101,15 @@ function listLayer(scope, { projectPath, home, now = Date.now() } = {}) {
   return rows.sort((a, b) => b.fires - a.fires || b.created - a.created);
 }
 
+/** Every lesson ever written in a layer, including archived / merged / graduated ones (read-only, for stats). */
+function everLessons(scope, { projectPath, home } = {}) {
+  const out = [];
+  const scan = (d) => { let n = []; try { n = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of n) { if (e.isDirectory()) scan(path.join(d, e.name)); else if (e.name.endsWith('.md')) { const l = readLesson(path.join(d, e.name)); if (l) out.push(l); } } };
+  scan(layerDir(scope, projectPath, home));
+  return out;
+}
+
 const listAll = (o = {}) => [...listLayer('project', o), ...listLayer('user', o)];
 
 function triggerMatches(guard, c, name, input) {
@@ -136,18 +151,16 @@ function validateTrigger(raw, { cause, projectPath, home } = {}) {
   return { total, fired };
 }
 
-function add(o) {
-  const { scope, text, trigger, symptom, cause, paths, projectPath, home } = o;
-  if (scope !== 'user' && scope !== 'project') throw new Error('--scope must be user or project');
-  if (!text || !String(text).trim()) throw new Error('--text is required');
-  const type = o.type || (trigger ? 'pitfall' : (scope === 'user' ? 'pref' : 'fact'));
-  if (!TYPES.includes(type)) throw new Error(`--type must be one of ${TYPES.join('|')}`);
-  if (type === 'pitfall' && !trigger) throw new Error('a pitfall needs --trigger (it acts when the matching tool call is about to run)');
-  const replay = trigger ? validateTrigger(trigger, { cause, projectPath, home }) : null;
+function writeLesson(f) {
+  const { scope, text, type, trigger, symptom, paths, projectPath, home, extra, about, source } = f;
   const id = 'lesson-' + crypto.createHash('sha1').update(String(text) + Date.now()).digest('hex').slice(0, 8);
   const j = JSON.stringify;
   const fm = ['---', `name: ${id}`, `description: ${j(String(text).trim().split('\n')[0].slice(0, 160))}`, `type: ${type}`, `scope: ${scope}`,
     `created: ${new Date().toISOString()}`];
+  if (about) fm.push(`about: ${j(about)}`);
+  fm.push(`source: ${j(source || 'manual')}`);
+  if (extra && extra.fires) fm.push(`fires: ${extra.fires}`);
+  if (extra && extra.recurrences) fm.push(`recurrences: ${extra.recurrences}`);
   if (symptom) fm.push(`symptom: ${j(symptom)}`);
   if (paths && paths.length) fm.push('paths:', ...paths.map((x) => `  - ${j(x)}`));
   if (trigger) fm.push('triggers:', `  - ${j(trigger)}`);
@@ -155,9 +168,89 @@ function add(o) {
   const dir = layerDir(scope, projectPath, home);
   fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(path.join(dir, `${id}.md`), fm.join('\n'));
+  return id;
+}
+
+function capMessage(scope, rows) {
+  const top = lc.similarPairs(rows).slice(0, 3).map((p) => `  ${p.a.id} + ${p.b.id} (${p.score.toFixed(2)}): kenaz learn merge ${p.a.id} ${p.b.id} --text "<general rule>"`);
+  return `${scope} layer is at the cap of ${lc.MAX_ACTIVE_PER_LAYER} active lessons; merge or drop one first (kenaz learn review). Most similar pairs:\n${top.join('\n')}`;
+}
+
+function add(o) {
+  const { scope, text, trigger, symptom, cause, paths, projectPath, home } = o;
+  if (scope !== 'user' && scope !== 'project') throw new Error('--scope must be user or project');
+  if (!text || !String(text).trim()) throw new Error('--text is required');
+  if (o.about && o.about !== 'kenaz') throw new Error('--about only accepts kenaz (a lesson about Kenaz itself)');
+  const source = o.source || 'manual';
+  if (!/^(manual|correction-nudge|harvest:.+)$/.test(source)) throw new Error('--source must be correction-nudge, harvest:<item id> or manual');
+  const type = o.type || (trigger ? 'pitfall' : (scope === 'user' ? 'pref' : 'fact'));
+  if (!TYPES.includes(type)) throw new Error(`--type must be one of ${TYPES.join('|')}`);
+  if (type === 'pitfall' && !trigger) throw new Error('a pitfall needs --trigger (it acts when the matching tool call is about to run)');
+  const active = listLayer(scope, { projectPath, home });
+  if (!o.force) {
+    const dup = lc.findSimilar(active, text);
+    if (dup) {
+      logUse(scope, projectPath, home, dup.id, 'recurrence');
+      if (source.startsWith('harvest:')) hv.markHarvested(projectPath, source.slice(8));
+      return { id: dup.id, scope, type: dup.type, recurred: true, recurrences: lc.bumpRecurrence(dup) };
+    }
+  }
+  if (active.length >= lc.MAX_ACTIVE_PER_LAYER) throw new Error(capMessage(scope, active));
+  const replay = trigger ? validateTrigger(trigger, { cause, projectPath, home }) : null;
+  const id = writeLesson({ scope, text, type, trigger, symptom, paths, projectPath, home, about: o.about, source });
+  if (source.startsWith('harvest:')) hv.markHarvested(projectPath, source.slice(8));
   return { id, type, scope, replay };
 }
 
+/** One general lesson replaces several: sources move to <layer>/archive/merged/ with merged_into. */
+function merge(ids, o) {
+  if (!Array.isArray(ids) || ids.length < 2) throw new Error('merge needs at least two lesson ids');
+  if (!o.text || !String(o.text).trim()) throw new Error('--text "<general rule>" is required');
+  const all = listAll(o);
+  const src = ids.map((id) => {
+    const l = all.find((x) => x.id === id);
+    if (!l) throw new Error(`no active lesson '${id}'`);
+    return l;
+  });
+  if (new Set(src.map((l) => l.scope)).size > 1) throw new Error('lessons to merge must be in the same layer');
+  const scope = src[0].scope;
+  const type = o.type || src[0].type;
+  if (!TYPES.includes(type)) throw new Error(`--type must be one of ${TYPES.join('|')}`);
+  const trigger = o.trigger || src[0].triggers[0];
+  if (type === 'pitfall' && !trigger) throw new Error('a pitfall needs --trigger');
+  if (o.trigger) validateTrigger(o.trigger, o);
+  const id = writeLesson({ scope, text: o.text, type, trigger, paths: [...new Set(src.flatMap((l) => l.paths))],
+    projectPath: o.projectPath, home: o.home, about: src.find((l) => l.about) ? src.find((l) => l.about).about : null,
+    extra: { fires: src.reduce((n, l) => n + l.fires, 0), recurrences: src.reduce((n, l) => n + l.recurrences, 0) } });
+  for (const l of src) lc.archiveTo(l, 'merged', { merged_into: id });
+  return { id, scope, type, merged: src.map((l) => l.id) };
+}
+
+function graduate(id, to, o = {}) {
+  if (!to || !String(to).trim()) throw new Error('--to "<commit sha or file path>" is required');
+  const l = listAll(o).find((x) => x.id === id);
+  if (!l) throw new Error(`no active lesson '${id}'`);
+  lc.archiveTo(l, 'graduated', { graduated_to: String(to).trim() });
+  return l;
+}
+
+const reviewAll = (o = {}) => lc.review([listLayer('project', o), listLayer('user', o)], o.now);
+
+/** Read-only counts for `kenaz stats`: per layer active, fires in the window, recurrences, graduated / merged / archived. */
+function stats({ projectPath, home, now = Date.now(), days = 14 } = {}) {
+  const count = (dir) => { try { return fs.readdirSync(dir).filter((n) => n.endsWith('.md')).length; } catch (_) { return 0; } };
+  const out = {};
+  for (const scope of ['project', 'user']) {
+    const rows = listLayer(scope, { projectPath, home, now, readOnly: true });
+    const dir = path.join(layerDir(scope, projectPath, home), 'archive');
+    let fires = 0;
+    for (const u of Object.values(readUses(usageLog(scope, projectPath, home)))) fires += u.times.filter((t) => now - t <= days * DAY_MS).length;
+    out[scope] = { active: rows.length, fires, recurrences: rows.reduce((n, l) => n + l.recurrences, 0),
+      graduated: count(path.join(dir, 'graduated')), merged: count(path.join(dir, 'merged')), archived: count(dir) };
+  }
+  return out;
+}
+
 function rm(id, o = {}) {
   const l = listAll(o).find((x) => x.id === id);
   if (!l) throw new Error(`no active lesson '${id}'`);
@@ -184,24 +277,42 @@ function dispatchLessons(projectPath, scopePaths = [], { home, now } = {}) {
   return out;
 }
 
-/** Boot banner: counts plus the user's preferences (short). Also runs the 30-day archive. */
+/** Boot banner: counts, a nudge when lessons need graduating or a layer nears the cap, and the newest prefs (max 10). */
 function bannerLines(projectPath, o = {}) {
   const proj = listLayer('project', { ...o, projectPath });
   const usr = listLayer('user', o);
-  if (!proj.length && !usr.length) return [];
-  const lines = [`[learn] project ${proj.length}, user ${usr.length} (kenaz learn list)`];
-  for (const l of usr.filter((x) => x.type === 'pref').slice(0, 3)) lines.push(`[learn] pref: ${l.text.split('\n')[0].slice(0, 120)}`);
+  let open = 0;
+  try { open = hv.openCount(projectPath, Date.now(), { sync: o.syncHarvest, refresh: o.refreshHarvest }); } catch (_) { /* optional */ }
+  if (!proj.length && !usr.length) return lc.bannerNotice([], open);
+  const lines = [`[learn] project ${proj.length}, user ${usr.length} (kenaz learn list)`, ...lc.bannerNotice([proj, usr], open)];
+  const prefs = usr.filter((x) => x.type === 'pref').sort((a, b) => b.created - a.created);
+  for (const l of prefs.slice(0, BANNER_PREFS)) lines.push(`[learn] pref: ${l.text.split('\n')[0].slice(0, 120)}`);
+  if (prefs.length > BANNER_PREFS) lines.push(`[learn] +${prefs.length - BANNER_PREFS} more`);
   return lines;
 }
 
 function flags(argv) {
   const f = { _: [] };
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i].startsWith('--')) f[argv[i].slice(2)] = argv[++i]; else f._.push(argv[i]);
+    if (argv[i] === '--force') f.force = true;
+    else if (argv[i].startsWith('--')) f[argv[i].slice(2)] = argv[++i]; else f._.push(argv[i]);
   }
   return f;
 }
 
+function printReview(r, out, extras) {
+  const row = (l) => `${l.id}  ${l.scope}/${l.type}  fired ${l.recent}x in 30d, recurred ${l.recurrences}x  ${l.text.split('\n')[0].slice(0, 80)}`;
+  if (!r.candidates.length && !r.oldPrefs.length && !r.pairs.length && !r.aboutKenaz.length && !extras) out('nothing to review');
+  if (r.candidates.length) out('Graduation candidates (make it code in this project: a test, a hook check, or a rule in the project\'s CLAUDE.md/AGENTS.md; then kenaz learn graduate <id> --to <commit or file>):');
+  for (const l of r.candidates) out(`  ${row(l)}`);
+  if (r.oldPrefs.length) out('Prefs older than 90 days (ask the user: confirm, or drop with kenaz learn rm <id>):');
+  for (const l of r.oldPrefs) out(`  ${l.id}  ${l.text.split('\n')[0].slice(0, 100)}`);
+  if (r.pairs.length) out('Merge pairs (kenaz learn merge <id1> <id2> --text "<general rule>"):');
+  for (const p of r.pairs) out(`  ${p.a.id} + ${p.b.id}  similarity ${p.score.toFixed(2)}`);
+  if (r.aboutKenaz.length) out('Lessons about Kenaz itself (report it: kenaz_wish_create scope=kenaz):');
+  for (const l of r.aboutKenaz) out(`  ${l.id}  ${l.text.split('\n')[0].slice(0, 100)}`);
+}
+
 function main(argv, out = console.log) {
   const f = flags(argv);
   const o = { projectPath: f['project-path'] || process.cwd(), home: f.home };
@@ -209,20 +320,34 @@ function main(argv, out = console.log) {
   try {
     if (sub === 'add') {
       const r = add({ ...o, scope: f.scope, text: f.text, type: f.type, trigger: f.trigger, symptom: f.symptom, cause: f.cause,
-        paths: f.paths ? f.paths.split(',') : [] });
-      out(`learned ${r.id} (${r.scope}/${r.type})${r.replay ? `; trigger fires on ${r.replay.fired}/${r.replay.total} recent tool calls` : ''}`);
+        paths: f.paths ? f.paths.split(',') : [], force: f.force, about: f.about, source: f.source });
+      if (r.recurred) out(`recurred ${r.id} (${r.recurrences} times)`);
+      else out(`learned ${r.id} (${r.scope}/${r.type})${r.replay ? `; trigger fires on ${r.replay.fired}/${r.replay.total} recent tool calls` : ''}`);
     } else if (sub === 'list') {
       const rows = listAll(o);
       if (!rows.length) out('no lessons yet (kenaz learn add --scope user|project --text ...)');
       for (const l of rows) {
         out(`${l.id}  ${l.scope}/${l.type}  fired ${l.fires}x  last ${l.lastFired ? new Date(l.lastFired).toISOString().slice(0, 10) : '-'}  ${l.text.split('\n')[0].slice(0, 100)}`);
       }
+    } else if (sub === 'merge') {
+      const r = merge(f._.slice(1), { ...o, text: f.text, type: f.type, trigger: f.trigger });
+      out(`merged ${r.merged.join(', ')} into ${r.id} (${r.scope}/${r.type})`);
+    } else if (sub === 'graduate') {
+      out(`graduated ${graduate(f._[1], f.to, o).id} -> ${f.to}`);
+    } else if (sub === 'review') {
+      const items = hv.harvest(o), sugg = hv.metrics(o);
+      printReview(reviewAll(o), out, items.length + sugg.length);
+      hv.print(items, sugg, out);
+    } else if (sub === 'harvest') {
+      const items = hv.harvest(o);
+      if (!items.length) out('no history items to harvest');
+      hv.print(items, [], out);
     } else if (sub === 'rm') {
       out(`removed ${rm(f._[1], o).id}`);
     } else if (sub === 'banner') {
       for (const l of bannerLines(o.projectPath, o)) out(l);
     } else {
-      out('usage: kenaz learn <add --scope user|project --text <lesson> [--type pref|fact|pitfall|check] [--trigger "<tool regex> | <input regex>"] [--symptom <text>] [--paths a,b] [--cause <command>] | list | rm <id>>');
+      out('usage: kenaz learn <add --scope user|project --text <lesson> [--type pref|fact|pitfall|check] [--trigger "<tool regex> | <input regex>"] [--symptom <text>] [--paths a,b] [--cause <command>] [--about kenaz] [--source correction-nudge|harvest:<id>|manual] [--force] | list | rm <id> | review | harvest | merge <id1> <id2> ... --text <general rule> [--type t] [--trigger r] | graduate <id> --to <commit or file>>');
       return 2;
     }
     return 0;
@@ -231,4 +356,4 @@ function main(argv, out = console.log) {
 
 if (require.main === module) process.exit(main(process.argv.slice(2)));
 
-module.exports = { add, rm, listLayer, listAll, dispatchLessons, bannerLines, validateTrigger, userDir, projectDir, main, ARCHIVE_AFTER_MS };
+module.exports = { add, rm, merge, graduate, reviewAll, stats, MAX_ACTIVE_PER_LAYER: lc.MAX_ACTIVE_PER_LAYER, listLayer, listAll, dispatchLessons, bannerLines, validateTrigger, everLessons, readLesson, readUses, usageLog, userDir, projectDir, main, ARCHIVE_AFTER_MS };