@lorekit/cli 1.43.0 → 1.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/core/lessons.mjs

@@ -12,7 +12,9 @@ import { deriveScope } from '../scope.mjs';
 // the injected set is chosen by ONE scorer, and a future `memory.relevant` verb
 // must be able to reuse it rather than grow a second ranking with its own idea
 // of what "most useful" means.
-import { resolvePrecedence, rankLessons, diversifyRankedLessons } from '../lessons-pure.mjs';
+import {
+  resolvePrecedence, rankLessons, diversifyRankedLessons, capPerBucket, loopBucketOf,
+} from '../lessons-pure.mjs';
 // The store's own scope inventory, normalised — the SAME helper `memory.scopes`
 // uses, so the map and the MCP tool cannot disagree about what a scope holds or
 // about what a failed enumeration looks like.
@@ -62,6 +64,20 @@ import { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 // shape the common one.
 const HARD_LESSON_CEILING = 40;
 
+// How many lessons any ONE self-improvement loop (`loop::<bucket>` tag) may
+// contribute to a session-start injection. A prolific loop — the pr-reviewer's
+// `loop::review-outcomes` / `loop::reviewer-comment-relevance`, or
+// `loop::implement-suggestion-lessons` — writes constantly and recently, so it
+// wins recency AND (being built to recur) salience, and a whole scope's read
+// can collapse to one bot's private bookkeeping (observed: 13 of 15 slots).
+// Ranking and MMR cannot fix that — the flood is real, varied, and high-scoring
+// — but it is not what a GENERAL coding session needs; those lessons are read
+// back by their own host through a tag filter. Two per bucket keeps the signal
+// (a loop's top couple of lessons still surface) without the flood; general,
+// non-loop lessons are never capped. Bounded, not shaped: on a store with no
+// loop lessons it never binds.
+const SESSION_START_LOOP_CAP = 2;
+
 // How many lessons ride along with the scope map in `map` mode. Small on
 // purpose: the point of that shape is the inventory, and a "map" that is mostly
 // lessons is just `index` with extra steps.
@@ -178,6 +194,25 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   const rankOpts = { terms: [], now, scopeOrder: scope.readOrder };
   const ranked = rankLessons(winners, rankOpts);
 
+  // AUDIENCE CAP before diversification: no single self-improvement loop may
+  // take more than `SESSION_START_LOOP_CAP` of the injected slots, so a general
+  // session is not flooded with one bot's private `loop::<bucket>` bookkeeping.
+  // General (non-loop) lessons pass through uncapped — they are what the cap
+  // frees room for. Applied to the ranked list so the survivors are each
+  // bucket's HIGHEST-ranked few, then diversified below. The scope map and
+  // `applicable` still read from the full `ranked` set — the cap governs what is
+  // shown, not the honest count of what exists per scope.
+  //
+  // WHERE THE FREED SLOTS FILL FROM, stated so the cap is not oversold. Each
+  // scope is read only to its newest `SCOPE_READ_LIMIT`, so on a scope whose
+  // recent writes are ALL one loop's, the general lessons that fill the freed
+  // slots come from the OTHER scopes in `readOrder` (a repo's loop churn makes
+  // room for `global` principles) — not from that same scope's older generals,
+  // which the bounded read never fetched. Reaching those is the recency-window
+  // limit (the `order=rank` CANDIDATE_LIMIT problem, one scope down), not this
+  // cap's to solve; the cap still does its job of unflooding across scopes.
+  const capped = capPerBucket(ranked, { cap: SESSION_START_LOOP_CAP, bucketOf: loopBucketOf });
+
   // ── the scope map: EXACT counts when the store can enumerate ───────────────
   //
   // The map's job is to tell a reader how much lore is sitting in each scope
@@ -250,7 +285,7 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // "8 of 50" stays true no matter how the render is bounded.
   return {
     scope,
-    lessons: diversifyRankedLessons(ranked, { ...rankOpts, k: HARD_LESSON_CEILING }),
+    lessons: diversifyRankedLessons(capped, { ...rankOpts, k: HARD_LESSON_CEILING }),
     scopeCounts,
     applicable: ranked.length,
   };

package/src/lessons-pure.mjs

@@ -745,3 +745,65 @@ export function diversifyRankedLessons(entries = [], {
   const limit = numberOr(k, list.length);
   return selectDiverse(list, limit, { scores, lambda });
 }
+
+/**
+ * The loop BUCKET a lesson belongs to, or null for a general (non-loop) lesson.
+ *
+ * A self-improvement loop writes into a `loop::<bucket>` tag namespace
+ * (`loop::review-outcomes`, `loop::implement-suggestion-lessons`, …) — the
+ * bucket convention `lorekit-setup` installs. Those lessons are a host's PRIVATE
+ * working memory, read back by that host through a tag filter; a general session
+ * reading a whole scope should not let one prolific loop's bookkeeping take
+ * every slot. Returns the first `loop::`-prefixed tag — the group key a cap
+ * counts against, matching `inferKindHost`'s first-recognised-wins order — or
+ * null when the lesson carries no loop tag (general knowledge, never capped).
+ * Keys on the `loop::` PREFIX convention ONLY; it re-encodes no specific bucket
+ * name, so a new loop bucket groups correctly without a code change here.
+ */
+export function loopBucketOf(entry) {
+  const tags = Array.isArray(entry?.tags) ? entry.tags : [];
+  for (const t of tags) {
+    if (typeof t !== 'string') continue;
+    const tag = t.trim();
+    if (tag.startsWith('loop::') && tag.length > 'loop::'.length) return tag;
+  }
+  return null;
+}
+
+/**
+ * Cap how many lessons any one bucket may contribute, preserving input order.
+ *
+ * Walks the (already-ranked) list once: a lesson whose `bucketOf` is null is
+ * ALWAYS kept — those are the general lessons the cap exists to protect — and a
+ * bucketed lesson is kept only while its bucket is still under `cap`. So one
+ * loop's dozen recent rows no longer evict every general lesson; at most `cap`
+ * of them survive and the freed slots go to the next-ranked variety. Pure and
+ * total: a non-array input is []; `cap: 0` drops every bucketed lesson (read
+ * ONLY general knowledge) while still keeping the null-bucket ones — a negative
+ * cap is not finite-and-non-negative, so `numberOr` reads it as "no cap", not as
+ * a stricter zero; a missing
+ * `bucketOf` treats everything as general (a no-op cap). `cap` is coerced with
+ * the module's `numberOr` convention (as `diversifyRankedLessons` does for `k`),
+ * so a `NaN`/absent cap falls back to "no cap" rather than silently dropping
+ * every bucketed lesson, while a stringy `'2'` still caps.
+ */
+export function capPerBucket(entries, { cap = Infinity, bucketOf } = {}) {
+  if (!Array.isArray(entries)) return [];
+  const of = typeof bucketOf === 'function' ? bucketOf : () => null;
+  const limit = numberOr(cap, Infinity);
+  const counts = new Map();
+  const out = [];
+  for (const e of entries) {
+    const bucket = of(e);
+    if (bucket == null) {
+      out.push(e);
+      continue;
+    }
+    const n = counts.get(bucket) ?? 0;
+    if (n < limit) {
+      counts.set(bucket, n + 1);
+      out.push(e);
+    }
+  }
+  return out;
+}