@lorekit/cli 1.42.0 → 1.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.42.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 } 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.
@@ -167,7 +183,35 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // first-appearance default — they agree today, but the hierarchy is
   // `readOrder`'s to state, not an artefact of how this function happens to
   // build its array.
-  const ranked = rankLessons(winners, { terms: [], now, scopeOrder: scope.readOrder });
+  // ONE options object feeds both the ranking and the diversification below, so
+  // the two can never drift: `diversifyRankedLessons` recomputes each entry's
+  // score to seed the MMR objective, and if its `terms`/`now`/`weights` differed
+  // from what `rankLessons` sorted on, those scores would not line up with the
+  // order — the near-identical `now` clock especially. Sharing the object makes
+  // that agreement structural rather than a thing two call sites have to keep in
+  // step by hand. `k` is diversification-only; `scopeOrder` is ranking-only and
+  // simply ignored by the diversifier's destructuring.
+  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 ───────────────
   //
@@ -219,12 +263,29 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
     ? scopeInventoryFromStore(inventory.scopes, scope.readOrder, derivedCounts)
     : derivedCounts;
 
+  // DIVERSIFY before the ceiling, so the budget is not spent on near-identical
+  // lessons. Ranking answers "which lessons score highest"; on an active repo
+  // the highest cluster is often one task's iteration log — a dozen
+  // `review-outcomes::pr395-it{3,4,5}` rows that score alike AND read alike, so
+  // a plain top-N hands the reader the same lesson several times and evicts the
+  // variety underneath. `diversifyRankedLessons` applies the SAME MMR
+  // (`selectDiverse`, λ=0.7 lexical Jaccard) the hosted `order=rank` path
+  // already uses, which was defined and exported here but never wired into the
+  // session-start read. It seeds with the top-ranked lesson (score is still
+  // 0.7 of the objective) and only spends the remaining 0.3 pushing down a
+  // lesson that repeats one already shown — so the best lesson stays first and
+  // the set stops being a wall of duplicates. `terms: []` matches the
+  // `rankLessons` call above (relevance contributes nothing at session start),
+  // which the scores MUST agree with. The scope map and `applicable` still read
+  // from `ranked` — the map is a pointer to what EXISTS per scope, a question
+  // diversification does not change.
+  //
   // `applicable` is the honest denominator for the header — how many the reader
   // has, as opposed to how many fitted. It is counted BEFORE the ceiling, so
   // "8 of 50" stays true no matter how the render is bounded.
   return {
     scope,
-    lessons: ranked.slice(0, HARD_LESSON_CEILING),
+    lessons: diversifyRankedLessons(capped, { ...rankOpts, k: HARD_LESSON_CEILING }),
     scopeCounts,
     applicable: ranked.length,
   };

package/src/lessons-pure.mjs

@@ -706,3 +706,104 @@ export function rankLessons(entries = [], {
   return scored.map((s) => s.entry);
 }
 
+/**
+ * Rank-then-diversify in one call — the `.mjs` twin's convenience for what the
+ * TS twin gets for free by carrying `{ entry, score }` pairs into `selectDiverse`.
+ *
+ * `selectDiverse` needs a parallel `scores` array, and those scores MUST be the
+ * same set-relative values the list was sorted on: the salience factor is
+ * normalised against the max `seen_count` in the candidate SET, so a score
+ * recomputed over a different population would not line up with the order. This
+ * helper recomputes the scores over exactly the list it diversifies, beside the
+ * unexported `seenCountFrom`/`scoreWithTerms`, so callers can apply MMR without
+ * reconstructing that alignment (and without `seenCountFrom` leaking out).
+ *
+ * `entries` is expected to be `rankLessons` output (best-first) so the seed of
+ * the greedy MMR is the top-ranked lesson; the pass-through
+ * `terms`/`weights`/`halfLifeDays`/`now` MUST match the `rankLessons` call that
+ * produced it, or the recomputed scores diverge from the sort. `k` caps the
+ * returned count (default: all). Empty/degenerate input returns `[]`.
+ */
+export function diversifyRankedLessons(entries = [], {
+  terms = [],
+  now = Date.now(),
+  weights = DEFAULT_RANK_WEIGHTS,
+  halfLifeDays = RECENCY_HALF_LIFE_DAYS,
+  k = Infinity,
+  lambda,
+} = {}) {
+  const list = Array.isArray(entries) ? entries.filter((e) => e && typeof e === 'object') : [];
+  if (list.length === 0) return [];
+  const termSet = distinctTerms(terms);
+  let maxSeenCount = 0;
+  for (const e of list) maxSeenCount = Math.max(maxSeenCount, seenCountFrom(e));
+  const scores = list.map((e) => scoreWithTerms(e, termSet, { now, weights, maxSeenCount, halfLifeDays }));
+  // `numberOr` is the module's coercion convention: a non-finite `k` (the
+  // `Infinity` default, `null`, or a stringy `'40'`) resolves to a real cap —
+  // the default falls through to the whole list, `'40'` becomes 40 — rather than
+  // silently returning everything on a shape a caller plausibly passes.
+  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;
+}