@lorekit/cli 1.43.0 → 1.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.43.0",
+  "version": "1.45.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.
@@ -95,8 +111,12 @@ const MAX_SCAN_CHARS = 4096;
 // is the follow-up that replaces this.
 export const SCOPE_READ_LIMIT = 25;
 
-export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
-  const scope = deriveScope(cwd);
+// `scope` may be injected instead of derived from `cwd` — a seam for callers
+// that already hold a resolved scope and for tests that need a deterministic
+// branch (deriveScope shells out to git, so the ambient branch — often a
+// detached `HEAD` in CI — cannot exercise the branch-seeded read otherwise).
+export async function fetchLessons(store, cwd, { now = Date.now(), scope: scopeOverride = null } = {}) {
+  const scope = scopeOverride || deriveScope(cwd);
   // Issued BEFORE the per-scope read loop and awaited after it. Nothing in the
   // inventory depends on the loop, so awaiting it afterwards would cost a
   // remote store one extra SERIAL round-trip on the session-start path; started
@@ -161,23 +181,44 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // narrow scope should instead be guaranteed floor space, that is a weighting
   // change in `rankLessons`, not something to re-derive here.
   //
-  // `terms: []` is the SessionStart case: nothing has been asked yet, so the
-  // relevance factor contributes nothing and the order is recency + salience.
-  // `scopeOrder` is passed explicitly rather than left to the scorer's
-  // 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.
+  // The rank options (see `sessionRankOpts`): a relevance query distilled from
+  // the branch NAME, at the DEFAULT weight, so a session on `feat/embedding-…`
+  // nudges embedding lessons up. Relevance only ever LIFTS an on-topic lesson —
+  // a non-matching lesson scores relevance 0, so a branch that matches nothing
+  // does not reorder the read — which is why it need not (and must not, per the
+  // Σweights normalisation) be damped by a smaller weight. A trunk branch or
+  // detached HEAD yields no terms, and the read is recency + salience exactly as
+  // before. `scopeOrder` is passed explicitly rather than left to the scorer's
+  // first-appearance default — the hierarchy is `readOrder`'s to state, not an
+  // artefact of how this function happens to build its array.
   // 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
+  // the two can never drift on terms, weights OR the `now` clock:
+  // `diversifyRankedLessons` recomputes each entry's score to seed the MMR
+  // objective, and scored with different options those would not line up with the
+  // sorted order. `k` is diversification-only; `scopeOrder` is ranking-only and
   // simply ignored by the diversifier's destructuring.
-  const rankOpts = { terms: [], now, scopeOrder: scope.readOrder };
+  const rankOpts = sessionRankOpts(scope, now);
   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
@@ -239,18 +280,19 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // 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.
+  // the set stops being a wall of duplicates. Spreading `rankOpts` here (rather
+  // than restating terms/weights) is what keeps the diversifier's recomputed
+  // scores in agreement with the `rankLessons` sort above — same terms, same
+  // branch-relevance weight, same `now`. 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: diversifyRankedLessons(ranked, { ...rankOpts, k: HARD_LESSON_CEILING }),
+    lessons: diversifyRankedLessons(capped, { ...rankOpts, k: HARD_LESSON_CEILING }),
     scopeCounts,
     applicable: ranked.length,
   };
@@ -506,6 +548,53 @@ export function distilTerms(text) {
   return terms;
 }
 
+// Single-segment branch names that carry no topic: the trunk names a session is
+// most often on. A `<segment>/…` branch always has a leading type/author segment
+// (`feat`, `fix`, `claude`, `dependabot`, a username) that is never the topic —
+// see `branchQueryTerms` — so those words don't need listing here; this set is
+// only consulted for a branch with NO `/`.
+const TRUNK_BRANCHES = new Set(['main', 'master', 'develop', 'trunk', 'head']);
+
+// Distil a relevance query from the branch NAME only — owner/repo never enters,
+// because `deriveScope` keeps the raw branch in `scope.branch`. The leading
+// `/`-segment of a branch is a type or author by convention (`feat/…`,
+// `dependabot/…`, `alice/…`) and never the topic, so it is dropped WHOLESALE when
+// a `/` is present; the DESCRIPTION is then tokenised by the shared `distilTerms`
+// (so `MIN_TERM_LEN`, dedupe and the FTS-safe shape apply). A word like `release`
+// survives when it is in the description (`feat/release-notes`), because only the
+// FIRST segment is removed. Empty for a bare trunk name, a detached `HEAD`, or no
+// git — the read then behaves exactly as before. Pure and total.
+export function branchQueryTerms(scope) {
+  const branch = scope && typeof scope.branch === 'string' ? scope.branch : '';
+  if (!branch || branch === 'HEAD') return [];
+  const slash = branch.indexOf('/');
+  if (slash === -1) {
+    // No prefix segment: a bare trunk name carries no topic; anything else is
+    // its own description.
+    return TRUNK_BRANCHES.has(branch.toLowerCase()) ? [] : distilTerms(branch);
+  }
+  return distilTerms(branch.slice(slash + 1));
+}
+
+// The rank options for a session-start read of `scope` at `now` — THE wiring
+// seam, so the branch-seeding is unit-testable without a git checkout. The branch
+// query rides at the DEFAULT relevance weight, exactly like the prompt/failure
+// paths: it only ever LIFTS an on-topic lesson (a non-matching lesson scores
+// relevance 0, so a branch that matches nothing is byte-for-byte the old read),
+// and it is deliberately NOT damped by a smaller weight — reducing one factor's
+// weight shrinks the normaliser (Σweights) and rescales every score, which then
+// distorts the unscaled Jaccard term in `selectDiverse`'s MMR even for lessons
+// the branch never matched. `fetchLessons` feeds the ONE object this returns to
+// both `rankLessons` and (spread) the diversifier, so their scores agree on
+// terms and the clock.
+export function sessionRankOpts(scope, now) {
+  return {
+    terms: branchQueryTerms(scope),
+    now,
+    scopeOrder: scope && scope.readOrder ? scope.readOrder : null,
+  };
+}
+
 // De-duplicate store-search hits by `scope::key` and cap them, PRESERVING the
 // store's order — which is NOT relevance ordering: the remote store filters by
 // FTS but orders by `updated_at desc` (recency), and the local one yields scope

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;
+}