@lorekit/cli 1.31.0 → 1.32.1

package/bin/lorekit.mjs

@@ -600,7 +600,7 @@ const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'threshold', 'help', 'version', 'telemetry',
-  'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
+  'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "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/lessons-view.mjs

@@ -37,16 +37,39 @@ export function scopeList({ projectScope, branchScope, repoScope } = {}) {
   return [...new Set([projectScope, branchScope, repoScope, 'global'].filter(Boolean))];
 }
 
+// Infer { kind, host } from a memory's loop tags — the CLI-local mirror of
+// `@lorekit/schemas` `inferKindHost` (the CLI has no schemas dependency). Kept
+// deliberately small and in lockstep with that source, including the 64-char
+// host clamp. Lets the offline store, whose rows carry no kind/host column,
+// still be filtered and badged by taxonomy from the tags it does store.
+function inferKindHostFromTags(tags) {
+  if (!Array.isArray(tags)) return {};
+  for (const tag of tags) {
+    if (tag === 'loop::review-outcomes') return { kind: 'bus', host: 'review' };
+    if (tag === 'loop::reviewer-comment-relevance') return { kind: 'signal', host: 'reviewer' };
+    const m = typeof tag === 'string' ? /^loop::(.+)-lessons$/.exec(tag) : null;
+    if (m && m[1] && m[1].length <= 64) return { kind: 'lesson', host: m[1] };
+  }
+  return {};
+}
+
 // Normalize an entry from either store (local markdown row or hosted DB row)
 // into one stable shape the view + `--json` output can rely on. Remote rows may
-// spell the timestamp `updated_at`; local rows use `updated`.
+// spell the timestamp `updated_at`; local rows use `updated`. When a row carries
+// no explicit kind/host (every offline row, and any remote row written before
+// migration 00056), fall back to the taxonomy inferred from its tags so the
+// badge and the `--kind`/`--host` filter behave the same in both sections.
 export function normalizeEntry(e = {}) {
+  const tags = Array.isArray(e.tags) ? e.tags : [];
+  const inferred = inferKindHostFromTags(tags);
   return {
     scope: e.scope ?? null,
     key: e.key ?? null,
     value: e.value == null ? '' : String(e.value),
     updated: e.updated ?? e.updated_at ?? null,
-    tags: Array.isArray(e.tags) ? e.tags : [],
+    tags,
+    kind: e.kind ?? inferred.kind ?? null,
+    host: e.host ?? inferred.host ?? null,
   };
 }
 
@@ -407,13 +430,27 @@ export function clusterDuplicates(entries = [], threshold = 0.8) {
 // `store.list({scope})` contract. Returns ordered per-scope groups plus a total
 // — a per-scope read failure is captured on the group, never thrown, so one bad
 // scope can't abort the listing. `store` may be a local or remote store.
-export async function gather(store, scopes) {
+export async function gather(store, scopes, filters = {}) {
+  // Parse the taxonomy filters into value sets. `filters` is passed to the store
+  // too (the remote narrows server-side); we ALSO post-filter the normalized
+  // entries here so the offline store — which ignores kind/host in its own
+  // `list()` — stays consistent with remote. Post-filtering the remote rows is
+  // idempotent (they were already narrowed) and matches on the same inferred
+  // taxonomy a row without explicit columns gets in normalizeEntry.
+  const wanted = (v) =>
+    v == null ? null : new Set(String(v).split(',').map((s) => s.trim()).filter(Boolean));
+  const kindSet = wanted(filters.kind);
+  const hostSet = wanted(filters.host);
+  const keep = (e) =>
+    (!kindSet || (e.kind != null && kindSet.has(e.kind))) &&
+    (!hostSet || (e.host != null && hostSet.has(e.host)));
+
   const groups = [];
   let total = 0;
   for (const scope of scopes) {
     let res;
     try {
-      res = await store.list({ scope });
+      res = await store.list({ scope, ...filters });
     } catch (e) {
       res = { ok: false, networkError: (e && e.message) || 'error' };
     }
@@ -421,7 +458,7 @@ export async function gather(store, scopes) {
       groups.push({ scope, entries: [], error: describeError(res) });
       continue;
     }
-    const entries = (res.entries || []).map(normalizeEntry);
+    const entries = (res.entries || []).map(normalizeEntry).filter(keep);
     total += entries.length;
     groups.push({ scope, entries, error: null });
   }
@@ -456,7 +493,11 @@ export function renderSection(header, section) {
     }
     for (const e of g.entries) {
       const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
-      log(`    ${c.cyan('•')} ${g.scope}::${e.key}${when}`);
+      // Taxonomy badge — the kind (and host, when known) so the three families
+      // are visible at a glance in the list. Omitted for rows written before the
+      // taxonomy existed (NULL kind).
+      const badge = e.kind ? ` ${c.dim(`[${e.kind}${e.host ? `·${e.host}` : ''}]`)}` : '';
+      log(`    ${c.cyan('•')} ${g.scope}::${e.key}${badge}${when}`);
       if (e.value) log(`      ${c.dim(preview(e.value))}`);
     }
   }

package/src/list.mjs

@@ -41,6 +41,11 @@ export async function list(args) {
   // Default to every applicable scope; `--scope <s>` narrows to one (an explicit
   // scope outside the applicable set is honoured — the user asked for it).
   const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
+  // Optional taxonomy filters — `--kind lesson --host reviewer` narrows to one
+  // family/owner. Comma lists are honoured by the remote store's query builder.
+  const filters = {};
+  if (typeof args.kind === 'string') filters.kind = args.kind;
+  if (typeof args.host === 'string') filters.host = args.host;
 
   // `--link` short-circuits: print the Explorer deep link for the current
   // context (the most-specific applicable scope, or `--scope`), no store reads.
@@ -64,9 +69,9 @@ export async function list(args) {
   // agent-facing control model enforces, honored here in the human read view.
   const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
-  const offline = localDenied ? { groups: [], total: 0 } : await gather(local, scopes);
+  const offline = localDenied ? { groups: [], total: 0 } : await gather(local, scopes, filters);
   const remoteAvailable = !remoteDenied && remote.usable();
-  const remoteResult = remoteAvailable ? await gather(remote, scopes) : { groups: [], total: 0 };
+  const remoteResult = remoteAvailable ? await gather(remote, scopes, filters) : { groups: [], total: 0 };
 
   const offlineSection = localDenied
     ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }

package/src/store/remote.mjs

@@ -58,10 +58,12 @@ class RemoteStore {
 
   // ── Memory operations → REST ──────────────────────────────────────────────
 
-  async list({ scope, tags, limit } = {}) {
+  async list({ scope, tags, kind, host, limit } = {}) {
     const p = new URLSearchParams();
     if (scope) p.set('scope', scope);
     if (tags?.length) p.set('tags', Array.isArray(tags) ? tags.join(',') : tags);
+    if (kind) p.set('kind', Array.isArray(kind) ? kind.join(',') : kind);
+    if (host) p.set('host', Array.isArray(host) ? host.join(',') : host);
     if (limit) p.set('limit', String(limit));
     const res = await this._rest(`/memories?${p}`);
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
@@ -92,13 +94,15 @@ class RemoteStore {
 
   async write(args = {}) {
     const {
-      scope, key, value, tags, source_agent, trigger, org, ttl_days, clear_ttl, created_at,
+      scope, key, value, tags, source_agent, trigger, kind, host, org, ttl_days, clear_ttl, created_at,
       origin_repo, origin_branch, origin_commit, origin_pr,
     } = args;
     const body = { scope, key, value };
     if (tags !== undefined) body.tags = tags;
     if (source_agent !== undefined) body.source_agent = source_agent;
     if (trigger !== undefined) body.trigger = trigger;
+    if (kind !== undefined) body.kind = kind;
+    if (host !== undefined) body.host = host;
     if (org !== undefined) body.org = org;
     if (ttl_days !== undefined) body.ttl_days = ttl_days;
     if (clear_ttl !== undefined) body.clear_ttl = clear_ttl;

package/src/write.mjs

@@ -120,6 +120,10 @@ export async function write(args) {
   const tags = args.tags ? String(args.tags).split(',').map((t) => t.trim()).filter(Boolean) : [];
   const sourceAgent = typeof args['source-agent'] === 'string' ? args['source-agent'] : undefined;
   const trigger = typeof args.trigger === 'string' ? args.trigger : undefined;
+  // Taxonomy overrides. Omitted → the server infers kind/host from a
+  // `loop::<host>-lessons` tag, so a tagged write needs neither flag.
+  const kind = typeof args.kind === 'string' ? args.kind : undefined;
+  const host = typeof args.host === 'string' ? args.host : undefined;
   // `--ttl-days` is validated HERE, at the flag seam, rather than being left to the
   // store: a truthiness test silently swallowed `--ttl-days 0` (falsy) and
   // `--ttl-days abc` (NaN, dropped again by the `ttl_days` spread further down), so
@@ -258,6 +262,8 @@ export async function write(args) {
     ...(tags.length ? { tags } : {}),
     ...(sourceAgent ? { source_agent: sourceAgent } : {}),
     ...(trigger ? { trigger } : {}),
+    ...(kind ? { kind } : {}),
+    ...(host ? { host } : {}),
     ...(ttlDays ? { ttl_days: ttlDays } : {}),
     ...(clearTtl ? { clear_ttl: true } : {}),
     ...(orgSlug ? { org: orgSlug } : {}),