@lorekit/cli 1.59.1 → 1.61.0

package/README.md

@@ -487,13 +487,62 @@ against the map and never reads the filesystem or resolves scope from the
 current directory — the changed-set can come from a real `git diff`, a PR
 file list, or by hand, from anywhere.
 
-Exits 0 by default; `--strict` exits non-zero when any PATH obligation is
-unmet. `--json` → `{ files, matched, unmet, ok }`. CLI-only (`native` — no MCP
+Each entry declares a `state`: `advisory` is reported but gates nothing,
+`gating` fails `--strict`, `retired` is not reported. An entry may only be
+`gating` if it has a `guard` — something independent of this map that already
+asserts the partnership — so the two guard-less entries (`perf-index`,
+`error-code-doc`) stay advisory by construction, enforced in the tests. Entries
+also name the recurrence CLASS they instantiate rather than a bare lesson key,
+so obligations sharing a root cause read as one problem.
+
+Exits 0 by default; `--strict` exits non-zero when a GATING entry's PATH
+obligation is unmet, `--strict-all` on ANY unmet obligation regardless of
+state. `--json` → `{ files, matched, unmet, unmetGating, ok, okGating }`. CLI-only (`native` — no MCP
 tool, no REST route, no `tool-catalog.ts` entry): a path-matching lint utility
 is not an operation surface. Slice 1 of a larger design — wiring a
 `PreToolUse` hook to call this at edit time, and server-side retrieval
 changes, are named follow-ups, not built here.
 
+### `lorekit invariants candidates`
+
+The compile pipeline's candidate scan — `cluster → groom-merge → compile
+candidate → invariant`. A **read-only** survey that reuses `dedupe`'s Jaccard
+clustering over the memory store, then ranks the clusters worth compiling
+into a hand-written `obligations-map.mjs` entry:
+
+```bash
+lorekit invariants candidates
+lorekit invariants candidates --min-seen-count 5 --json
+lorekit invariants candidates --scope repo::owner/repo
+```
+
+A cluster is a candidate when the **summed `seen_count`** across its members
+is at least `--min-seen-count` (default `3`), or any member's own
+`<!-- meta: seen_count=… status=… trigger-context="…" -->` comment (the
+convention documented in the `lorekit-setup` skill's
+`self-improvement-loops.md`) already declares a non-`"active"` status.
+Candidates are ranked by (summed `seen_count` × distinct scopes), descending.
+**For each candidate it prints every memory the merge would collapse** —
+that list is the whole point of the command.
+
+It reuses the same `dedupe` ↔ `recurrence-clusters.mjs` join, so a candidate
+whose members already resolve to a named recurrence class is flagged as a
+stronger case ("this should join an existing invariant") than a merely
+similar one ("this might be a new class").
+
+It deliberately does **not** classify a `trigger-context` into a
+glob/command/error-shape — that judgment is the human step the compile
+pipeline's "never auto-compile, never auto-gate" rule protects, so the raw
+string is printed, never interpreted — and it does **not** know about
+`compiled_to` (no such field exists yet, so an already-compiled candidate can
+still surface here — a known, named gap, not a silent omission).
+
+Offline + Remote split like `dedupe`, with the same population cap. `--json`
+→ `{ root, scopes, minSeenCount, offline, remote }`; each candidate carries
+`members` (`scope`, `key`, `seenCount`, `meta`), `score`, and
+`recurrenceClass`. CLI-only (`native` — no MCP tool, no REST route, no
+`tool-catalog.ts` entry), matching how `obligations` is registered.
+
 ### `lorekit link` (alias `url`)
 
 Print a shareable **dashboard deep-link URL** to stdout — nothing else, so it
@@ -1047,14 +1096,16 @@ also returns their headroom against the plan's memory cap.
 | `--mcp-json` | Also write a committable project `.mcp.json` (auth via `${LOREKIT_TOKEN}`, no embedded token) for Claude Code on the web (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
-| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `obligations` / `link` / `purge` / `purge-expired`) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `obligations` / `invariants candidates` / `link` / `purge` / `purge-expired`) |
 | `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory. On `show` / `write` it **names** the scope, overriding the positional |
 | `--key <key>` | Name the key outright (`show` / `write` / `link`) — the way to address a key that itself contains `::` |
 | `--link` | Print the equivalent dashboard deep-link URL instead of running (`show` / `search` / `list` / `tree`) |
 | `--base <url>` | Dashboard base URL for deep links (`link` / `--link`; else `LOREKIT_APP_URL`, default `https://lorekit.io`) |
 | `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |
 | `--files <path>...` | Changed files to check (`obligations`); also accepted as positionals or newline-separated stdin |
-| `--strict` | Exit non-zero on any unmet obligation (`obligations`) |
+| `--strict` | Exit non-zero on an unmet obligation from a `gating` entry (`obligations`) |
+| `--strict-all` | Exit non-zero on ANY unmet obligation, advisory entries included (`obligations`) |
+| `--min-seen-count <n>` | Minimum summed `seen_count` for a cluster to be a candidate (`invariants candidates`; default `3`) |
 | `--retention-days <1..365>` | Only purge archived memories older than this (`purge`; default `30`, derived from the tool catalog) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |

package/bin/lorekit.mjs

@@ -81,7 +81,12 @@ ${c.bold('Commands')}
               files/actions and flags any partner NOT in the given set.
               Cwd-independent — matches path strings, never reads the FS.
               --files <path>..., positionals, or stdin (newline-separated).
-              --json, --strict (exit non-zero on any unmet obligation).
+              --json, --strict (exit non-zero on an unmet obligation from a gating entry).
+  invariants  \`invariants candidates\`: a read-only compile-pipeline scan —
+              reuses dedupe's clustering to rank near-duplicate memories as
+              merge candidates for a hand-written obligations-map.mjs entry.
+              Never auto-compiles or gates anything; prints every memory a
+              candidate would collapse. --json, --scope <s>, --min-seen-count <n>.
   link (url)  Print a shareable dashboard deep-link URL for the current context,
               a scope, or a specific lesson (opens its detail sheet). No args
               links to the cwd's most-specific scope. Filter flags mirror the
@@ -135,11 +140,13 @@ ${c.bold('Options')}
   -t, --token <token>     LoreKit token (lk_rw_* to allow writes, lk_ro_* read-only)
       --mode <mode>       Memory mode: off | local | remote (doctor override)
       --store <path>      Local project-tier store directory (default: .lorekit)
-      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe / obligations / link)
+      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe / obligations / invariants / link)
+      --min-seen-count <n> Minimum summed seen_count for a cluster to be a candidate (invariants candidates; default 3)
       --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe / link)
                           On show / write it NAMES the scope, overriding the positional
       --files <path>...   Changed files to check (obligations); also accepted as positionals or newline-separated stdin
-      --strict            Exit non-zero on any unmet obligation (obligations)
+      --strict            Exit non-zero on an unmet obligation from a gating entry (obligations)
+      --strict-all        Exit non-zero on ANY unmet obligation, advisory entries included (obligations)
       --key <key>         Name the key explicitly (show / write / link) — the way to
                           address a key that itself contains \`::\`
       --link              Print the equivalent dashboard deep-link URL instead of running (show / search / list / tree)
@@ -633,6 +640,39 @@ ${c.bold('Examples')}
   npx @lorekit/cli obligations supabase/functions/_shared/audit/audit.ts
   npx @lorekit/cli obligations --files packages/schemas/src/shared/tool-catalog.ts --json
   git diff --name-only origin/main... | npx @lorekit/cli obligations --strict
+`,
+  invariants: `${c.bold('lorekit invariants candidates')} — the compile pipeline's candidate scan
+
+${c.bold('Usage')}
+  npx @lorekit/cli invariants candidates [options]
+
+A read-only survey that reuses dedupe's Jaccard clustering to find
+near-duplicate memories, then ranks the clusters worth compiling into a
+hand-written obligations-map.mjs entry. It never auto-compiles and never
+gates anything — it prints candidates for a HUMAN to review. For each
+candidate it prints every memory the merge would collapse, which is the
+whole point of the command.
+
+A cluster is a candidate when the summed seen_count across its members is at
+least --min-seen-count, or a member's own \`<!-- meta: ... status=... -->\`
+comment already declares a non-"active" status. Ranked by (summed seen_count
+× distinct scopes), descending. It does not classify a trigger-context into a
+glob/command/error-shape (a human step), and it does not know about
+compiled_to (no such field exists yet), so an already-compiled candidate can
+still surface here.
+
+${c.bold('Options')}
+  -d, --dir <path>          Target project root (default: current directory)
+      --scope <scope>       Restrict to a single scope (default: all applicable)
+      --min-seen-count <n>  Minimum summed seen_count for a candidate (default: 3)
+      --json                Machine-readable output (candidates + members)
+  -e, --endpoint <url>      Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>       Remote token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>        Local project-tier store directory (default: .lorekit)
+
+${c.bold('Examples')}
+  npx @lorekit/cli invariants candidates
+  npx @lorekit/cli invariants candidates --min-seen-count 5 --json
 `,
   link: `${c.bold('lorekit link')} — print a shareable dashboard deep-link URL ${c.dim('(alias: url)')}
 
@@ -1028,12 +1068,14 @@ const KNOWN_FLAGS = [
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
   // Scale-aware survey flags
   'all', 'max', 'since', 'until', 'key-prefix', 'cluster-by-key',
+  // `invariants candidates`
+  'min-seen-count',
   // groom / policy / protect / pin / unpin
   'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'run',
   'name', 'mode', 'enabled', 'disabled',
   'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'off',
   // `obligations`
-  'files', 'strict',
+  'files', 'strict', 'strict-all',
 ];
 
 async function main() {
@@ -1046,7 +1088,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'strict'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'strict', 'strict-all'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/src/commands/dedupe.mjs

@@ -16,6 +16,7 @@ import { deriveScope } from '../shared/scope.mjs';
 import { resolveDenies } from '../shared/control.mjs';
 import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
 import { scopeList, gather, gatherStream, clusterDuplicates, clusterDuplicatesBlocked, clusterByKeyPattern, compileKeyPattern, DEFAULT_MAX } from '../shared/lessons-view.mjs';
+import { resolveRecurrenceClass } from '../shared/recurrence-clusters.mjs';
 import { log, heading, status, err, c } from '../shared/util.mjs';
 
 const DEFAULT_THRESHOLD = 0.8;
@@ -37,6 +38,15 @@ const DEDUPE_POP_CAP = 2000;
 // so we floor to a tiny epsilon rather than accept a literal 0.
 const MIN_THRESHOLD = Number.EPSILON;
 
+// Attach the compile-pipeline join to every cluster: does this dedupe cluster
+// already resolve to a NAMED recurrence class (`recurrence-clusters.mjs`)?
+// Unconditional, like `withReadFields` — additive decoration, never a flag,
+// since a null `recurrenceClass` costs nothing and a match is worth surfacing
+// on every run rather than behind an opt-in.
+function attachRecurrenceClasses(clusters) {
+  return clusters.map((cl) => ({ ...cl, recurrenceClass: resolveRecurrenceClass(cl.members) }));
+}
+
 // Parse `--threshold` into a number in (0, 1]; anything unparseable or out of
 // range falls back to the default (never a crash on bad input). Pure-ish helper.
 export function parseThreshold(raw) {
@@ -189,9 +199,9 @@ export async function dedupe(args) {
       }
       return {
         available: true,
-        clusters: byKeyMode
-          ? clusterByKeyPattern(entries, keyPattern)
-          : clusterDuplicatesBlocked(entries, threshold),
+        clusters: attachRecurrenceClasses(
+          byKeyMode ? clusterByKeyPattern(entries, keyPattern) : clusterDuplicatesBlocked(entries, threshold),
+        ),
         errored: flat.errored,
         popCapped,
       };
@@ -199,9 +209,9 @@ export async function dedupe(args) {
     const { entries, errored, popCapped } = await streamAccumulate(store);
     return {
       available: true,
-      clusters: byKeyMode
-        ? clusterByKeyPattern(entries, keyPattern)
-        : clusterDuplicatesBlocked(entries, threshold),
+      clusters: attachRecurrenceClasses(
+        byKeyMode ? clusterByKeyPattern(entries, keyPattern) : clusterDuplicatesBlocked(entries, threshold),
+      ),
       errored,
       popCapped,
     };
@@ -318,6 +328,10 @@ function renderDedupeSection(header, section) {
       signal = `${cluster.size} memories, similarity ${range}`;
     }
     log(`  ${c.yellow('•')} cluster ${n} ${c.dim(`(${signal})`)}`);
+    if (cluster.recurrenceClass?.classId) {
+      const pureTag = cluster.recurrenceClass.pure ? ' — pure' : ' — partial';
+      log(`    ${c.dim(`class: ${cluster.recurrenceClass.className}${pureTag}`)}`);
+    }
     for (const m of cluster.members) {
       log(`    ${c.cyan('-')} ${m.scope}::${m.key}`);
     }

package/src/commands/invariants.mjs

@@ -0,0 +1,304 @@
+// `lorekit invariants <candidates>` — the compile pipeline's candidate scan.
+//
+//   cluster  →  groom-merge  →  compile candidate  →  invariant
+//
+// `candidates` is a read-only survey over the memory store that reuses
+// `dedupe`'s Jaccard clustering to find near-duplicate lessons, then ranks
+// the clusters worth compiling into a hand-written `obligations-map.mjs`
+// entry. It never auto-compiles and never gates anything — it prints
+// candidates for a human to review, per the compile pipeline's "never
+// auto-compile, never auto-gate" rule (see `../shared/recurrence-clusters.mjs`
+// and `../shared/obligations-map.mjs`'s `state` ladder). For each candidate it
+// prints EVERY memory the merge would collapse — that list is the whole
+// point of the command, so it is the default view, not behind `--verbose`.
+//
+// Criteria (pure scoring in `../shared/candidates-pure.mjs`):
+//   - summed seen_count across a cluster's members >= --min-seen-count
+//     (default 3), OR any member's `<!-- meta: ... status=... -->` comment
+//     already declares a non-"active" status
+//   - ranked by (summed seen_count × distinct scopes), descending
+//
+// What this deliberately does NOT do:
+//   - classify a trigger-context into a glob/command/error-shape. The raw
+//     `trigger-context` string (when a lesson's meta comment carries one) is
+//     printed verbatim, never interpreted — "parses into a detectable
+//     trigger" is the human step the compile pipeline protects.
+//   - check `compiled_to`. No such field exists yet (no schema, no server
+//     support — see the kickoff's Open Questions), so a candidate already
+//     compiled into an obligations-map.mjs entry can still surface here. A
+//     known, named gap until `compiled_to` lands, not a silent omission.
+//
+// Value-mode clustering only (the same `clusterDuplicatesBlocked` heuristic
+// `dedupe` defaults to) — key-shape clustering (`dedupe --cluster-by-key`) is
+// a naming-debt signal, not a recurrence-candidate one, and stays dedupe's.
+//
+// Reads raw store rows directly (skipping `gather()`/`gatherStream()`'s
+// `normalizeEntry`, which drops `seen_count`) because this scan's whole
+// premise is the seen_count signal that `dedupe` never needed. Offline +
+// Remote split and the same memory-safety population cap as `dedupe`.
+//
+// Registered `native` (CLI-only, no MCP tool, no REST route, no
+// `tool-catalog.ts` entry) — matching how `obligations` is registered.
+import process from 'node:process';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, clusterDuplicatesBlocked, DEFAULT_MAX } from '../shared/lessons-view.mjs';
+import { rankCandidates } from '../shared/candidates-pure.mjs';
+import { resolveRecurrenceClass } from '../shared/recurrence-clusters.mjs';
+import { seenCountOf } from '../store/entry-fields.mjs';
+import { log, heading, status, err, c } from '../shared/util.mjs';
+
+const DEFAULT_THRESHOLD = 0.8;
+const DEFAULT_MIN_SEEN_COUNT = 3;
+// Mirrors dedupe's memory-safety population cap — the same super-linear
+// clustering step runs here.
+const POP_CAP = 2000;
+const STREAM_PAGE_LIMIT = 100;
+
+function errorMessage(res) {
+  return res?.networkError ?? res?.error?.message ?? res?.error ?? 'error';
+}
+
+// Local store is exhaustive and has no server-side narrowing (mirrors
+// dedupe's local branch) — gather everything, then filter/cap in JS. Raw rows
+// (not run through normalizeEntry) so seen_count survives.
+async function localRawEntries(store, scopes, { keyPrefix, since, until, max }) {
+  const entries = [];
+  const errored = [];
+  for (const scope of scopes) {
+    let res;
+    try {
+      res = await store.list({ scope });
+    } catch (e) {
+      res = { ok: false, networkError: (e && e.message) || 'error' };
+    }
+    if (!res || res.ok === false) {
+      errored.push({ scope, error: errorMessage(res) });
+      continue;
+    }
+    for (const e of res.entries || []) entries.push({ ...e, scope: e.scope ?? scope });
+  }
+  let filtered = entries;
+  if (keyPrefix) filtered = filtered.filter((e) => typeof e.key === 'string' && e.key.startsWith(keyPrefix));
+  if (since) filtered = filtered.filter((e) => !e.created || e.created >= since);
+  if (until) filtered = filtered.filter((e) => !e.created || e.created < until);
+  if (filtered.length > max) filtered = filtered.slice(0, max);
+  let popCapped = false;
+  if (filtered.length > POP_CAP) {
+    filtered = filtered.slice(0, POP_CAP);
+    popCapped = true;
+  }
+  return { entries: filtered, errored, popCapped };
+}
+
+// Remote: paginate via cursor with the same param names gatherStream forwards
+// server-side, but skip normalizeEntry so seen_count survives.
+async function remoteRawEntries(store, scopes, { keyPrefix, since, until, max }) {
+  const entries = [];
+  const errored = [];
+  let popCapped = false;
+  let surveyed = 0;
+  for (const scope of scopes) {
+    if (popCapped || surveyed >= max) break;
+    let cursor;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const remaining = max - surveyed;
+      if (remaining <= 0) break;
+      const pageLimit = Math.min(STREAM_PAGE_LIMIT, remaining);
+      let res;
+      try {
+        res = await store.list({
+          scope,
+          limit: pageLimit,
+          cursor,
+          ...(since ? { created_since: since } : {}),
+          ...(until ? { created_until: until } : {}),
+          ...(keyPrefix ? { key_prefix: keyPrefix } : {}),
+        });
+      } catch (e) {
+        res = { ok: false, networkError: (e && e.message) || 'error' };
+      }
+      if (!res || res.ok === false) {
+        errored.push({ scope, error: errorMessage(res) });
+        break;
+      }
+      for (const e of res.entries || []) {
+        if (entries.length >= POP_CAP) {
+          popCapped = true;
+          break;
+        }
+        entries.push({ ...e, scope: e.scope ?? scope });
+      }
+      surveyed += (res.entries || []).length;
+      if (popCapped || !res.hasMore || !res.nextCursor) break;
+      cursor = res.nextCursor;
+      if (surveyed >= max) break;
+    }
+  }
+  return { entries, errored, popCapped };
+}
+
+// Cluster raw entries (clusterDuplicatesBlocked only reads .scope/.key/.value,
+// so raw rows work unmodified), then re-attach seenCount/value per member —
+// the clusterer's own output narrows members down to {scope,key}.
+function buildCandidates(entries, { threshold, minSeenCount }) {
+  const byAddress = new Map(entries.map((e) => [`${e.scope}::${e.key}`, e]));
+  const clusters = clusterDuplicatesBlocked(entries, threshold).map((cl) => ({
+    ...cl,
+    members: cl.members.map((m) => {
+      const raw = byAddress.get(`${m.scope}::${m.key}`);
+      return { scope: m.scope, key: m.key, seenCount: seenCountOf(raw), value: raw?.value ?? '' };
+    }),
+  }));
+  return rankCandidates(clusters, { minSeenCount, resolveClass: resolveRecurrenceClass });
+}
+
+async function candidates(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  const threshold = DEFAULT_THRESHOLD;
+  const minSeenCount = args['min-seen-count'] !== undefined ? Number(args['min-seen-count']) : DEFAULT_MIN_SEEN_COUNT;
+
+  const scopeInfo = deriveScope(root);
+  const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const surveyMax = args.max !== undefined ? Number(args.max) : DEFAULT_MAX;
+  const surveySince = args.since || undefined;
+  const surveyUntil = args.until || undefined;
+  const surveyKeyPrefix = args['key-prefix'] || undefined;
+  const narrow = { keyPrefix: surveyKeyPrefix, since: surveySince, until: surveyUntil, max: surveyMax };
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : await (async () => {
+        const { entries, errored, popCapped } = await localRawEntries(local, scopes, narrow);
+        return { available: true, candidates: buildCandidates(entries, { threshold, minSeenCount }), errored, popCapped };
+      })();
+
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteSection = remoteAvailable
+    ? await (async () => {
+        const { entries, errored, popCapped } = await remoteRawEntries(remote, scopes, narrow);
+        return { available: true, candidates: buildCandidates(entries, { threshold, minSeenCount }), errored, popCapped };
+      })()
+    : {
+        available: false,
+        reason: remoteDenied
+          ? `disabled by deny constraint (${remoteDenied.source})`
+          : remoteUnavailableReason(connection),
+      };
+
+  const offlineCount = offlineSection.available ? offlineSection.candidates.length : 0;
+  const remoteCount = remoteSection.available ? remoteSection.candidates.length : 0;
+
+  if (args.json) {
+    log(
+      JSON.stringify(
+        {
+          root,
+          scopes,
+          minSeenCount,
+          offline: sectionJson(offlineSection),
+          remote: sectionJson(remoteSection),
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    heading('LoreKit invariants candidates');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+    log(`  ${c.dim(`criteria: summed seen_count >= ${minSeenCount}, or a member's meta status is non-"active"`)}`);
+
+    if (offlineSection.available && offlineSection.popCapped) {
+      log(`  ${c.yellow('!')} population cap (${POP_CAP}) reached for Offline — results are partial. Narrow with --key-prefix, --since, or --max.`);
+    }
+    if (remoteSection.available && remoteSection.popCapped) {
+      log(`  ${c.yellow('!')} population cap (${POP_CAP}) reached for Remote — results are partial. Narrow with --key-prefix, --since, or --max.`);
+    }
+
+    renderSection({ title: 'Offline' }, offlineSection);
+    renderSection({ title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined }, remoteSection);
+
+    log('');
+    const total = offlineCount + remoteCount;
+    if (total === 0) {
+      log(`  ${c.green('✓')} no compile candidates at this threshold`);
+    } else {
+      const plural = total === 1 ? '' : 's';
+      log(`  ${c.yellow('!')} ${total} candidate${plural} found — nothing here compiles or gates on its own; write an obligations-map.mjs entry by hand`);
+    }
+    log('');
+  }
+
+  return {
+    exitCode: 0,
+    'lorekit.cli.invariants.candidates.scope_count': scopes.length,
+    'lorekit.cli.invariants.candidates.offline_count': offlineCount,
+    'lorekit.cli.invariants.candidates.remote_count': remoteCount,
+    'lorekit.cli.invariants.candidates.remote_available': remoteAvailable,
+  };
+}
+
+function renderSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  for (const e of section.errored || []) {
+    log(`  ${c.bold(e.scope)}  ${c.yellow('!')} ${c.dim(e.error)}`);
+  }
+
+  if (!section.candidates.length) {
+    if (!(section.errored || []).length) log(`  ${c.dim('no compile candidates')}`);
+    return;
+  }
+
+  let n = 0;
+  for (const cand of section.candidates) {
+    n += 1;
+    log(`  ${c.yellow('•')} candidate ${n} ${c.dim(`(score ${cand.score}, ${cand.members.length} memories)`)}`);
+    if (cand.recurrenceClass?.classId) {
+      const pureTag = cand.recurrenceClass.pure ? ' — pure' : ' — partial';
+      log(`    ${c.dim(`class: ${cand.recurrenceClass.className}${pureTag}`)}`);
+    }
+    for (const m of cand.members) {
+      const fields = [`seen_count=${m.seenCount}`];
+      if (m.meta.status) fields.push(`status=${m.meta.status}`);
+      if (m.meta['trigger-context']) fields.push(`trigger-context=${JSON.stringify(m.meta['trigger-context'])}`);
+      log(`    ${c.cyan('-')} ${m.scope}::${m.key}  ${c.dim(`(${fields.join(', ')})`)}`);
+    }
+  }
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, candidates: [], errored: [] };
+  }
+  return { available: true, candidates: section.candidates, errored: section.errored || [] };
+}
+
+export async function invariants(args) {
+  const sub = args._[1];
+  if (sub === 'candidates') return candidates(args);
+
+  err(`${c.red('Usage:')} lorekit invariants <candidates> [options]`);
+  return { exitCode: 1 };
+}

package/src/commands/obligations.mjs

@@ -34,7 +34,16 @@
 //      stdin is not a TTY
 //
 // Exit code: 0 by default; 1 when `--strict` is given AND any path obligation
-// is unmet. `run:` obliges are advisory (`met: null`) and never gate.
+// belonging to a `gating` entry is unmet. `run:` obliges are advisory
+// (`met: null`) and never gate.
+//
+// `--strict` respects each entry's `state` (see `../shared/obligations-map.mjs`):
+// an `advisory` entry is reported and never gates, because an entry with no
+// independent `guard` asserts only its author's belief. `error-code-doc` is the
+// motivating case — its own note calls it "a documented path-proxy, not a
+// content predicate" that "may over-flag", and it was nonetheless failing
+// `--strict` on any edit to `mcp-handler.ts`. `--strict-all` restores the
+// previous behaviour of gating on every unmet obligation regardless of state.
 import process from 'node:process';
 import { log, heading, c } from '../shared/util.mjs';
 import { checkObligations } from '../shared/obligations-pure.mjs';
@@ -83,21 +92,25 @@ function dedupe(list) {
 
 export async function obligations(args) {
   const changedFiles = await resolveChangedFiles(args);
-  const strict = Boolean(args.strict);
+  const strictAll = Boolean(args['strict-all']);
+  const strict = Boolean(args.strict) || strictAll;
   const result = checkObligations({ changedFiles, map: SURFACE_PARTNER_MAP });
+  const gatingUnmet = strictAll ? result.unmet : result.unmetGating;
 
   if (args.json) {
-    log(JSON.stringify({ ...result, strict }, null, 2));
+    log(JSON.stringify({ ...result, strict, strictAll }, null, 2));
   } else {
     render(result, changedFiles);
   }
 
   return {
-    exitCode: strict && result.unmet > 0 ? 1 : 0,
+    exitCode: strict && gatingUnmet > 0 ? 1 : 0,
     'lorekit.cli.obligations.files': changedFiles.length,
     'lorekit.cli.obligations.matched': result.matched.length,
     'lorekit.cli.obligations.unmet': result.unmet,
+    'lorekit.cli.obligations.unmetGating': result.unmetGating,
     'lorekit.cli.obligations.strict': strict,
+    'lorekit.cli.obligations.strictAll': strictAll,
   };
 }
 
@@ -114,7 +127,11 @@ function render(result, changedFiles) {
 
   for (const entry of result.matched) {
     log('');
-    log(`  ${c.bold(entry.id)}${entry.guard ? c.dim(`  (guard: ${entry.guard})`) : ''}`);
+    const stateTag = entry.state === 'gating' ? c.dim('[gating]') : c.dim('[advisory]');
+    log(
+      `  ${c.bold(entry.id)} ${stateTag}${entry.guard ? c.dim(`  (guard: ${entry.guard})`) : c.dim('  (no guard — advisory only)')}`,
+    );
+    if (entry.cluster) log(`    ${c.dim(`class: ${entry.cluster.name}`)}`);
     if (entry.note) log(`    ${c.dim(entry.note)}`);
     for (const o of entry.obliges) {
       const mark = o.kind === 'action' ? c.cyan('•') : o.met ? c.green('✓') : c.yellow('!');
@@ -130,6 +147,12 @@ function render(result, changedFiles) {
   } else {
     const plural = result.unmet === 1 ? '' : 's';
     log(`  ${c.yellow('!')} ${result.unmet} unmet obligation${plural} — sweep the partner${plural} above`);
+    const advisoryOnly = result.unmet - result.unmetGating;
+    if (advisoryOnly > 0) {
+      log(
+        `    ${c.dim(`${result.unmetGating} from gating entries; ${advisoryOnly} advisory (reported, never gates)`)}`,
+      );
+    }
   }
   log('');
 }

package/src/commands.mjs

@@ -48,6 +48,7 @@ import { tree } from './commands/tree.mjs';
 import { lint } from './commands/lint.mjs';
 import { dedupe } from './commands/dedupe.mjs';
 import { obligations } from './commands/obligations.mjs';
+import { invariants } from './commands/invariants.mjs';
 import { link } from './commands/link.mjs';
 import { hook } from './commands/hook.mjs';
 import { migrate } from './commands/migrate.mjs';
@@ -83,6 +84,7 @@ export const COMMANDS = [
   { name: 'lint', run: lint, traced: true, strictFlags: true, native: 'quality pass over stored lessons' },
   { name: 'dedupe', run: dedupe, traced: true, strictFlags: true, native: 'near-duplicate detection across a scope' },
   { name: 'obligations', run: obligations, traced: true, strictFlags: true, native: 'checks changed files against the surface-partner map' },
+  { name: 'invariants', run: invariants, traced: true, strictFlags: true, native: 'compile-pipeline candidate scan over the memory store' },
   { name: 'link', run: link, traced: true, strictFlags: true, native: 'builds a dashboard deep link', aliases: ['url'] },
   { name: 'migrate', run: migrate, traced: true, strictFlags: true, native: 'moves lore between local and remote stores' },
   { name: 'bootstrap', run: bootstrap, traced: true, strictFlags: true, native: 'seeds a fresh store from a template' },