@lorekit/cli 1.32.0 → 1.33.0

package/package.json

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

package/skill/lorekit-setup/rules/self-improvement-loops.md

@@ -20,6 +20,7 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 - [Conventions](#conventions)
 - [Read step (start of every run)](#read-step-start-of-every-run)
 - [Write step (on failure / at the end of a run)](#write-step-on-failure--at-the-end-of-a-run)
+- [The reconcile-on-re-run flow (resolve + record)](#the-reconcile-on-re-run-flow-resolve--record)
 - [Promotion (fast → slow)](#promotion-fast--slow)
 - [Entrenchment guards (do not skip these)](#entrenchment-guards-do-not-skip-these)
 - [Wiring checklist](#wiring-checklist)
@@ -178,6 +179,70 @@ bar is stricter for `repo::` writes — a repo scope is team-visible.
 
 ---
 
+## The reconcile-on-re-run flow (resolve + record)
+
+Some hosts do not just fail-and-learn — they **produce durable outputs at a
+shared target that they revisit on later runs**: a reviewer posts comment threads
+on a PR it re-reviews on every push, a triager files issues it re-scans, a linter
+opens tickets it re-opens. For these, a plain read/write loop is not enough:
+stale outputs pile up at the target, and the signal about which outputs were
+*useful* is thrown away.
+
+The reconcile-on-re-run flow closes both gaps. On each re-run over the same
+target, the host **reconciles its own prior outputs** in three steps:
+
+1. **Classify** each prior output the host itself produced against the current
+   state of the target. The three outcomes that carry signal:
+
+   | Outcome | Meaning | Evidence |
+   | --- | --- | --- |
+   | **resolved** | The output was acted on — the thing it flagged is now handled | the flagged region changed and the finding no longer reproduces, or the owner acknowledged it |
+   | **declined** | The owner explicitly rejected it | a "won't fix" / "by design" reply, a 👎 |
+   | **still-open** | The finding still reproduces this run | the host re-produces the same output |
+
+2. **Clean up at the target.** For `resolved` and `declined` outputs, close them
+   at the source — resolve the thread, close the ticket, check the box — so a
+   re-run leaves the target tidier than it found it instead of accumulating
+   cruft. **Never** close a `still-open` output; that would hide a live finding.
+   Only ever touch outputs the host itself authored.
+
+3. **Record the outcome** to a **Signal**-shaped bucket (a durable, per-target
+   relevance memory — distinct from the fast lessons bucket). Write `resolved` as
+   a positive signal for that output's *pattern* and `declined` as a negative
+   one, keyed by a stable pattern fingerprint (never by a line number or an id
+   that drifts). Over runs this bucket teaches the host which of its output
+   patterns get acted on in this target and which are noise — read it at the
+   start of a run to suppress the reliably-declined patterns and reinforce the
+   reliably-resolved ones. `still-open` writes nothing: there is no outcome yet.
+
+   The Signal bucket is a second bucket alongside the lessons one, in the same
+   grammar as [Conventions](#conventions):
+
+   - **Tag:** `loop::<host>-<signal>` — e.g. `loop::reviewer-comment-relevance`.
+     Reads filter by it; writes always carry it.
+   - **Key:** `<host>-<signal>::<pattern-fingerprint>` — e.g.
+     `reviewer-comment-relevance::unsupported-cross-repo-claim`. The fingerprint
+     is the key segment, so the same `scope` + `key` overwrites in place and one
+     output pattern accumulates one record across runs.
+
+Two guards keep this honest, both instances of the entrenchment guards below:
+
+- **Absence of confirmation is not resolution.** If a re-run did not re-scan the
+  region a prior output covers (e.g. it only looked at the diff), the output is
+  `still-open`, not `resolved` — silence is not a fix.
+- **The cleanup is idempotent and non-fatal.** A target already closed is
+  skipped; a cleanup error is logged and never fails the run.
+
+Wire it as its own step at the host's re-run seam, gated on "a prior run's output
+exists at this target". It composes with the read/write steps: the Signal bucket
+it writes is read back at the next run's read step. The reference implementation
+is the `agent-skills` `pr-reviewer` agent: it resolves its own addressed PR
+threads on each commit-triggered re-review and records the fixed/declined
+outcome to a `reviewer-comment-relevance` bucket, whose classification and
+record shape are specified in `agents/shared/rules/comment-relevance-memory.md`.
+
+---
+
 ## Promotion (fast → slow)
 
 After a read or write, a lesson is **promotion-eligible** when either:

package/src/core/lessons.mjs

@@ -140,6 +140,12 @@ export function failureQuery(toolName, toolResponse) {
 // `cap`. Pure and best-effort: no terms or no lessons → empty (the caller then
 // falls back to the write-nudge alone). Preserves `lessons` order, so the
 // most-specific scope's relevant lesson surfaces first.
+//
+// This is the LITERAL, client-side matcher — it can only ever narrow a list it
+// is handed. On the failure hot path it has been superseded by
+// `relevantLessonsFromStore`, which QUERIES the store instead of post-filtering
+// the already-injected set (see that function's note). Kept for its unit tests
+// and as the pure building block behind the store-delegated ranking.
 export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
   if (!Array.isArray(lessons) || !lessons.length || !Array.isArray(terms) || !terms.length) {
     return [];
@@ -152,6 +158,79 @@ export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
   return out;
 }
 
+// Rank the store-search hits for a failure lookup. `resultsPerTerm` is one entry
+// list per failure term (a term that errored or matched nothing contributes an
+// empty list). A lesson that matched MORE terms is more relevant, so it ranks
+// higher; ties break toward the MORE-SPECIFIC scope (its position in
+// `readOrder`, which is most-specific-first) and then toward first-seen order
+// for a stable result. De-duplicates by `scope::key` across every term/scope,
+// keeping the first-seen entry. Pure and total — any non-array input degrades to
+// [] rather than throwing (this runs inside the best-effort failure hook).
+// Capped at `cap`.
+export function rankRelevant(resultsPerTerm, readOrder = [], cap = MAX_RELEVANT) {
+  if (!Array.isArray(resultsPerTerm)) return [];
+  const order = new Map(
+    (Array.isArray(readOrder) ? readOrder : []).map((s, i) => [s, i]),
+  );
+  const UNKNOWN = Number.MAX_SAFE_INTEGER; // a scope not in readOrder sorts last
+  const byId = new Map();
+  let seq = 0;
+  for (const entries of resultsPerTerm) {
+    if (!Array.isArray(entries)) continue;
+    const seenThisTerm = new Set(); // one term can't count a lesson twice
+    for (const e of entries) {
+      if (!e || !e.key) continue;
+      const id = `${e.scope ?? ''}::${e.key}`;
+      if (seenThisTerm.has(id)) continue;
+      seenThisTerm.add(id);
+      const cur = byId.get(id);
+      if (cur) {
+        cur.matches += 1;
+      } else {
+        byId.set(id, {
+          entry: e,
+          matches: 1,
+          rank: order.has(e.scope) ? order.get(e.scope) : UNKNOWN,
+          seq: seq++,
+        });
+      }
+    }
+  }
+  return [...byId.values()]
+    .sort((a, b) => b.matches - a.matches || a.rank - b.rank || a.seq - b.seq)
+    .slice(0, Math.max(0, cap))
+    .map((r) => r.entry);
+}
+
+// Retrieve lessons relevant to a tool failure by QUERYING the store across the
+// scope hierarchy — as opposed to `relevantLessons`, which post-filtered the
+// already-injected set and could therefore only ever resurface a lesson that was
+// going to be shown anyway (a lesson in a sibling scope, or one past the
+// per-scope read cap, was unreachable). Runs one search per distilled term
+// (bounded by `failureQuery`'s MAX_TERMS), concurrently and best-effort: a failed
+// or throwing search contributes nothing. Matching is DELEGATED to the store — a
+// literal substring over the full scope for the local store, server-side FTS
+// (with stemming, so `connect` matches `connection`) for the remote — then the
+// union is ranked by the pure `rankRelevant`. Returns [] on any failure so the
+// caller falls back to the write-nudge alone.
+export async function relevantLessonsFromStore(store, scope, terms, { cap = MAX_RELEVANT } = {}) {
+  if (!store || typeof store.search !== 'function') return [];
+  if (!scope || !Array.isArray(scope.readOrder) || scope.readOrder.length === 0) return [];
+  if (!Array.isArray(terms) || terms.length === 0) return [];
+  const scopes = scope.readOrder;
+  const resultsPerTerm = await Promise.all(
+    terms.map(async (t) => {
+      try {
+        const res = await store.search({ q: t, scopes });
+        return res && res.ok && Array.isArray(res.entries) ? res.entries : [];
+      } catch {
+        return []; // best-effort: one failed term never sinks the lookup
+      }
+    }),
+  );
+  return rankRelevant(resultsPerTerm, scopes, cap);
+}
+
 // Render the relevant-lessons block injected alongside the failure nudge, or
 // null when nothing matched. Same compact-index shape as `formatLessons`, with a
 // touch more hook per line (there are at most MAX_RELEVANT and they're directly

package/src/hook.mjs

@@ -13,7 +13,7 @@ import {
   retrospectiveNudge,
   failureNudge,
   failureQuery,
-  relevantLessons,
+  relevantLessonsFromStore,
   formatRelevantLessons,
   writeConfirmation,
 } from './core/lessons.mjs';
@@ -148,9 +148,13 @@ async function run(args) {
     try {
       const store = createStore(control);
       if (store) {
-        const { lessons } = await fetchLessons(store, root);
+        // QUERY the store across the scope hierarchy for lessons matching this
+        // failure — not a post-filter of the SessionStart-injected set, which
+        // could only ever resurface an already-shown lesson. Matching is the
+        // store's job (server FTS with stemming for remote, full-scope substring
+        // for local), so a paraphrased prior lesson can still surface.
         const terms = failureQuery(parsed.toolName, parsed.toolResponse);
-        relevant = formatRelevantLessons(relevantLessons(lessons, terms));
+        relevant = formatRelevantLessons(await relevantLessonsFromStore(store, scope, terms));
       }
     } catch {
       relevant = null; // never let a lesson lookup break the failure nudge