@lorekit/cli 1.60.0 → 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.60.0",
+  "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' },

package/src/shared/candidates-pure.mjs

@@ -0,0 +1,110 @@
+// Pure core for `lorekit invariants candidates` — ranks near-duplicate
+// clusters (the same Jaccard heuristic `dedupe` uses) as merge candidates for
+// a hand-written compile-pipeline invariant declaration.
+//
+// This module is deliberately read-only in a stronger sense than "no writes":
+// it never CLASSIFIES anything. It surfaces what a lesson already states about
+// itself (a parsed meta comment, a seen_count, a resolved recurrence class)
+// and ranks it — it does not decide whether a trigger-context is mechanically
+// detectable, and it does not validate `status` against a fixed vocabulary
+// (none is defined anywhere in this codebase yet). That judgment is the human
+// step the compile pipeline's "never auto-compile, never auto-gate" rule
+// protects; a scan that started making those calls would be the thing the
+// rule exists to prevent.
+//
+// Operates on already-enriched cluster members — `{ scope, key, seenCount,
+// value }` — leaving the store I/O and the seen_count/meta correlation to the
+// command (`../commands/invariants.mjs`). Zero-dep, total: malformed input
+// degrades to the empty/default case rather than throwing.
+
+const META_COMMENT_RE = /<!--\s*meta:([\s\S]*?)-->/;
+const META_FIELD_RE = /([\w-]+)=("(?:[^"\\]|\\.)*"|\S+)/g;
+
+/**
+ * Extract the `<!-- meta: seen_count=1 status=active expires=<iso>
+ * trigger-context="<signal>" -->` convention documented in the lorekit-setup
+ * skill's `self-improvement-loops.md`. Nothing in the CLI parses this
+ * convention today; this is read-only extraction for a human's judgment, not
+ * a schema the scan enforces. Absent or malformed input yields `{}`, never a
+ * throw — a lesson written before (or without) the convention is not an
+ * error, just a candidate with no meta fields.
+ */
+export function parseMetaComment(value) {
+  if (typeof value !== 'string') return {};
+  const m = META_COMMENT_RE.exec(value);
+  if (!m) return {};
+  const out = {};
+  META_FIELD_RE.lastIndex = 0;
+  let mm;
+  while ((mm = META_FIELD_RE.exec(m[1]))) {
+    const [, k, rawV] = mm;
+    out[k] =
+      rawV.startsWith('"') && rawV.endsWith('"') ? rawV.slice(1, -1).replace(/\\"/g, '"') : rawV;
+  }
+  return out;
+}
+
+function totalSeen(members) {
+  return (members || []).reduce((n, m) => n + (Number.isFinite(m.seenCount) ? m.seenCount : 0), 0);
+}
+
+function distinctScopeCount(members) {
+  return new Set((members || []).map((m) => m.scope)).size;
+}
+
+/**
+ * A cluster is a candidate when its recurrence signal is real: either the
+ * summed `seenCount` across members crosses `minSeenCount` (default 3 — the
+ * kickoff's "seen_count >= 3" criterion, applied to the SUM across the
+ * cluster's members rather than any single one, since the whole pitch of a
+ * candidate is "these N sightings are really one entry"), or a member's own
+ * meta comment already declares a non-"active" status.
+ */
+export function isCandidate(members, { minSeenCount = 3 } = {}) {
+  if (totalSeen(members) >= minSeenCount) return true;
+  return (members || []).some((m) => {
+    const status = parseMetaComment(m.value).status;
+    return typeof status === 'string' && status.length > 0 && status !== 'active';
+  });
+}
+
+/** Recurrence × distinct scopes — the ranking signal the kickoff names. */
+export function scoreCandidate(members) {
+  return totalSeen(members) * distinctScopeCount(members);
+}
+
+/**
+ * Filter a set of dedupe-style clusters down to candidates and rank them,
+ * highest score first (ties broken by member count, then the first member's
+ * `scope::key` for determinism). Each input cluster is
+ * `{ members: [{scope,key,seenCount,value}], size, minSimilarity?,
+ * maxSimilarity? }`. Never mutates the input.
+ *
+ * `resolveClass`, when supplied, is called with the cluster's raw members to
+ * attach a resolved recurrence class (the `dedupe` join, reused here) — a
+ * candidate already resolving to a known class is a stronger case ("this
+ * should join an existing invariant") than one that doesn't ("this might be a
+ * new class"). Optional so the pure ranking logic stays testable without it.
+ */
+export function rankCandidates(clusters, { minSeenCount = 3, resolveClass } = {}) {
+  return (clusters || [])
+    .filter((cl) => isCandidate(cl.members, { minSeenCount }))
+    .map((cl) => {
+      const members = (cl.members || []).map((m) => ({ ...m, meta: parseMetaComment(m.value) }));
+      return {
+        members,
+        size: cl.size ?? members.length,
+        minSimilarity: cl.minSimilarity,
+        maxSimilarity: cl.maxSimilarity,
+        recurrenceClass: typeof resolveClass === 'function' ? resolveClass(cl.members) : null,
+        score: scoreCandidate(cl.members),
+      };
+    })
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      if (b.size !== a.size) return b.size - a.size;
+      const aKey = `${a.members[0]?.scope}::${a.members[0]?.key}`;
+      const bKey = `${b.members[0]?.scope}::${b.members[0]?.key}`;
+      return aKey < bKey ? -1 : aKey > bKey ? 1 : 0;
+    });
+}

package/src/shared/completions.mjs

@@ -71,6 +71,8 @@ const FLAG = {
   'retention-days': { desc: 'Only purge archived older than n days', arg: 'n' },
   files: { desc: 'Changed files to check', arg: 'path' },
   strict: { desc: 'Exit non-zero on any unmet obligation' },
+  'strict-all': { desc: 'Exit non-zero on ANY unmet obligation, advisory included' },
+  'min-seen-count': { desc: 'Minimum summed seen_count for a candidate', arg: 'n' },
   'policy-id': { desc: 'Run/preview a saved policy', arg: 'id' },
   'min-age-days': { desc: 'Match lessons at least n days old', arg: 'n' },
   'unseen-days': { desc: 'Match lessons unseen for at least n days', arg: 'n' },
@@ -121,7 +123,9 @@ const COMMANDS = [
     flags: ['dir', 'scope', 'threshold', 'cluster-by-key', 'json', 'endpoint', 'token', 'store'] },
   { name: 'obligations', summary: 'Check changed files against the surface-partner map',
     positional: 'path',
-    flags: ['files', 'strict', 'json'] },
+    flags: ['files', 'strict', 'strict-all', 'json'] },
+  { name: 'invariants', summary: "Compile pipeline's candidate scan (`invariants candidates`)",
+    flags: ['dir', 'scope', 'min-seen-count', 'json', 'endpoint', 'token', 'store'] },
   { name: 'link', summary: 'Print a shareable dashboard deep-link URL', aliases: ['url'],
     positional: 'address',
     flags: ['dir', 'scope', 'key', 'q', 'owner', 'tags', 'range', 'from', 'to', 'archived', 'base', 'json'] },

package/src/shared/obligations-map.mjs

@@ -31,7 +31,32 @@
 //                                // when a name-derived module's real partner
 //                                // could live under either of two sibling
 //                                // directories)
-//     lessonKey: string,        // canonical memory key to cite
+//     state: 'advisory'|'gating'|'retired',
+//                                // advisory: reported, gates nothing.
+//                                // gating: fails --strict. An entry may only
+//                                // be `gating` if it has a `guard` — an
+//                                // independent source that already asserts
+//                                // the partnership. Without one, the entry
+//                                // asserts only its own author's belief, and
+//                                // `perf-index` / `error-code-doc` say as
+//                                // much in their notes. Enforced in
+//                                // obligations.test.mjs.
+//                                // retired: not checked; kept for provenance.
+//     cluster: string,          // the recurrence class this entry
+//                                // instantiates (`./recurrence-clusters.mjs`).
+//                                // Supplies the lesson key to cite, and
+//                                // groups entries that share a root cause.
+//     lessonKey?: string,       // an entry-specific memory key, overriding
+//                                // its cluster's canonical one. Rare.
+//     owner: string,            // who reviews this entry when it misfires.
+//                                // An entry with no owner is cruft with a CI
+//                                // job attached.
+//     added: string,            // ISO date
+//     reviewBy: string,         // ISO date. Memories expire; without this the
+//                                // map is the one place in the system under
+//                                // no decay pressure, and it accumulates the
+//                                // way the lesson variants it replaced did.
+//                                // Guard-less entries get a shorter horizon.
 //     guard?: string,           // the existing CI spec/script that enforces
 //                                // this partnership, if any
 //     note?: string,            // why this entry exists / its limitations
@@ -56,19 +81,6 @@
 
 import { mirrorPairs } from './mirror-pairs.mjs';
 
-// The flagship recurrence class: a partner copies a CLAIM (a mirrored
-// module's behavior, a generated artifact's content, a documented mechanism)
-// and goes stale when the source changes. Cited by every entry below whose
-// obligation is "this partner copies what you just changed."
-const COPIES_A_CLAIM_LESSON =
-  'implement-suggestion-lessons::a-mechanism-clause-you-correct-in-the-pr-body-must-be-corrected-in-every-doc-that-copies-it';
-
-// The registered-everywhere / sibling-set recurrence class: adding or moving
-// something that a SET of surfaces enumerates (a doc listing every command,
-// a generated mirror listing every file) re-flags every surface that lists
-// the set and now has a hole.
-const SIBLING_SET_LESSON = 'aw-lessons::docs-drift-grep-must-search-names-not-invocation';
-
 const EDGE_MIRROR_GUARD = 'packages/mcp-core/src/edge/edge-parity.spec.ts';
 
 // One `{ match, obliges }` row PER KNOWN PAIR, in both directions — see the
@@ -76,17 +88,25 @@ const EDGE_MIRROR_GUARD = 'packages/mcp-core/src/edge/edge-parity.spec.ts';
 const EDGE_MIRROR_ENTRIES = mirrorPairs.flatMap(({ core, edge }) => [
   {
     id: 'edge-mirror',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: edge,
     obliges: [core],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: EDGE_MIRROR_GUARD,
     note: 'An edge (Deno) module mirrored self-contained from mcp-core — edit one, mirror the other. Partner looked up from the shared mirror-pairs inventory, never reconstructed from an assumed-symmetric path.',
   },
   {
     id: 'edge-mirror-core',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: core,
     obliges: [edge],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: EDGE_MIRROR_GUARD,
     note: 'The reverse direction of edge-mirror — a mcp-core source file changed, its known edge mirror (from the same mirror-pairs inventory) is the partner.',
   },
@@ -96,6 +116,10 @@ export const SURFACE_PARTNER_MAP = [
   ...EDGE_MIRROR_ENTRIES,
   {
     id: 'tool-catalog',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: 'packages/schemas/src/shared/tool-catalog.ts',
     obliges: [
       'supabase/functions/mcp/tool-dispatch.generated.ts',
@@ -103,52 +127,84 @@ export const SURFACE_PARTNER_MAP = [
       'packages/web/public/llms.txt',
       'run:pnpm nx generate:llms schemas',
     ],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: 'packages/mcp-core/src/mcp-guards/tool-catalog-parity.spec.ts, scripts/codegen/gen-surfaces.mjs --check',
     note: 'The catalog is the single origin of the operation surface — every generated projection of it must be regenerated in the same commit.',
   },
   {
     id: 'llms-generated',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: ['packages/schemas/src/llms/template.md', 'packages/schemas/src/shared/tool-catalog.ts'],
     obliges: ['packages/web/public/llms.txt', 'run:pnpm nx generate:llms schemas'],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: 'packages/schemas/src/llms/render.spec.ts',
     note: 'llms.txt is GENERATED — never hand-edited; the committed file must be what the generator produces from these two sources.',
   },
   {
     id: 'docs-section',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: 're:^packages/web/src/content/docs/[^/]+\\.mdx$',
     obliges: ['packages/web/src/lib/docs/sections.ts'],
-    lessonKey: SIBLING_SET_LESSON,
+    cluster: 'sibling-set',
     guard: 'packages/web/src/lib/docs/sections.spec.ts',
     note: 'A new/removed docs page needs its DOCS_SECTIONS entry, or the site index and the page itself drift apart.',
   },
   {
     id: 'plugin-skill',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: 'packages/cli/skill/**',
     obliges: ['run:node scripts/codegen/sync-plugin-skill.mjs', 'plugins/lorekit-claude/skills/**'],
-    lessonKey: SIBLING_SET_LESSON,
+    cluster: 'sibling-set',
     guard: 'scripts/codegen/sync-plugin-skill.mjs --check',
     note: 'The Claude plugin vendors a copy of every skill/* source — regenerate the mirror, never hand-edit it.',
   },
+  {
+    id: 'cli-flag-doc',
+    state: 'advisory',
+    owner: '@mthines',
+    added: '2026-08-31',
+    reviewBy: '2026-11-30',
+    match: 'packages/cli/bin/lorekit.mjs',
+    obliges: ['docs/cli.md', 'packages/cli/README.md', 'CLAUDE.md'],
+    cluster: 'copies-a-claim',
+    guard: null,
+    note: 'The flag table and per-command help in bin/lorekit.mjs is the origin of every flag claim; docs/cli.md, the package README (prose AND its flag table) and CLAUDE.md each restate it. Found by running this command against its own changed-set while changing the meaning of --strict: nothing fired, because the map covered every generated surface and no hand-written one. A path proxy, not a content predicate — bin/lorekit.mjs changes for reasons unrelated to flags — so advisory by construction, like error-code-doc.',
+  },
   {
     id: 'perf-index',
+    state: 'advisory',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2026-11-26',
     match: 're:^supabase/migrations/.*index.*\\.sql$',
     obliges: ['supabase/tests/migrations.test.sql'],
-    lessonKey: SIBLING_SET_LESSON,
+    cluster: 'sibling-set',
     guard: null,
     note: 'Convention only — a real gap. A new index migration has no automated nudge to add its coverage to the migrations test.',
   },
   {
     id: 'error-code-doc',
+    state: 'advisory',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2026-11-26',
     match: ['supabase/functions/mcp/mcp-handler.ts', 'packages/mcp-core/src/auth/account-wide-tools.ts'],
     obliges: [
       'docs/mcp-tools.md',
       'packages/schemas/src/llms/template.md',
       'packages/web/public/llms.txt',
     ],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: null,
-    note: 'A documented path-proxy, not a content predicate — obligations sees file paths, not diffs, so it cannot tell an error-const edit from an unrelated one in the same file and may over-flag. Advisory only (never gates unless --strict, and even then it is one signal among several).',
+    note: 'A documented path-proxy, not a content predicate — obligations sees file paths, not diffs, so it cannot tell an error-const edit from an unrelated one in the same file and may over-flag. State is `advisory` for that reason: it is reported on every hit and gates nothing, not even under --strict (only --strict-all).',
   },
 ];

package/src/shared/obligations-pure.mjs

@@ -45,6 +45,8 @@
 // `stemOf` (below) is the simpler, general-purpose primitive — a plain
 // basename-without-extension — exported for standalone use and unit testing.
 
+import { clusterForEntry, lessonKeyForEntry } from './recurrence-clusters.mjs';
+
 export const RUN_PREFIX = 'run:';
 export const REGEX_PREFIX = 're:';
 
@@ -217,10 +219,15 @@ export function checkObligations({ changedFiles = [], map = [] } = {}) {
 
       let bucket = byId.get(entry.id);
       if (!bucket) {
+        const cluster = clusterForEntry(entry);
         bucket = {
           id: entry.id,
-          lessonKey: entry.lessonKey ?? null,
+          state: entry.state ?? 'advisory',
+          cluster: cluster ? { id: cluster.id, name: cluster.name, why: cluster.why } : null,
+          lessonKey: lessonKeyForEntry(entry),
           guard: entry.guard ?? null,
+          owner: entry.owner ?? null,
+          reviewBy: entry.reviewBy ?? null,
           note: entry.note ?? null,
           obliges: new Map(),
         };
@@ -232,15 +239,25 @@ export function checkObligations({ changedFiles = [], map = [] } = {}) {
     }
   }
 
-  const matched = [...byId.values()].map((b) => ({
-    id: b.id,
-    lessonKey: b.lessonKey,
-    guard: b.guard,
-    note: b.note,
-    obliges: [...b.obliges.values()],
-  }));
+  const matched = [...byId.values()]
+    .filter((b) => b.state !== 'retired')
+    .map((b) => ({
+      id: b.id,
+      state: b.state,
+      cluster: b.cluster,
+      lessonKey: b.lessonKey,
+      guard: b.guard,
+      owner: b.owner,
+      reviewBy: b.reviewBy,
+      note: b.note,
+      obliges: [...b.obliges.values()],
+    }));
+
+  const countUnmet = (entries) =>
+    entries.reduce((n, e) => n + e.obliges.filter((o) => o.met === false).length, 0);
 
-  const unmet = matched.reduce((n, e) => n + e.obliges.filter((o) => o.met === false).length, 0);
+  const unmet = countUnmet(matched);
+  const unmetGating = countUnmet(matched.filter((e) => e.state === 'gating'));
 
-  return { files, matched, unmet, ok: unmet === 0 };
+  return { files, matched, unmet, unmetGating, ok: unmet === 0, okGating: unmetGating === 0 };
 }

package/src/shared/recurrence-clusters.mjs

@@ -0,0 +1,161 @@
+// Recurrence clusters — the named classes of repeated failure that the
+// Surface-Partner Map's entries instantiate.
+//
+// This module formalizes something the map already did informally. Before it,
+// `obligations-map.mjs` held two bare string constants —
+// `COPIES_A_CLAIM_LESSON` and `SIBLING_SET_LESSON` — whose own comments called
+// them "the flagship recurrence class" and "the registered-everywhere /
+// sibling-set recurrence class". Eight entries, two classes: the clustering had
+// been done by hand and encoded as a variable name.
+//
+// Naming it makes three things possible that a bare constant does not:
+//
+//   1. A cluster can carry WHY it recurs and WHAT ITS SHAPE IS, not just which
+//      lesson key to cite. That text is what a human hitting the check needs.
+//   2. `checkObligations` can report the cluster alongside the entry, so two
+//      unmet obligations from the same root cause read as one problem.
+//   3. It is the join point for the compile pipeline: a cluster is what a
+//      candidates scan over the memory store produces (N near-duplicate
+//      memories that are really one class), and an invariant entry is what a
+//      human writes from a cluster. The `sourceKeys` field records that origin
+//      in the only direction currently available — from the entry back to the
+//      memories.
+//
+// Pure and zero-dep by design, like `obligations-pure.mjs`: no filesystem, no
+// cwd, no network. The registry is data.
+//
+// Cluster schema:
+//   {
+//     id: string,          // stable slug, referenced by map entries' `cluster`
+//     name: string,        // one line, the shape of the recurrence
+//     lessonKey: string,   // canonical memory key an entry in this class cites
+//     why: string,         // why this class recurs — shown on a hit
+//     sourceKeys?: string[] // other memory keys this class subsumes, if known
+//   }
+
+/**
+ * The named recurrence classes. Adding one is a deliberate act: a cluster
+ * asserts that several distinct memories are really one class, which is the
+ * claim a groom-merge would act on. Two entries sharing a `lessonKey` but not
+ * a cluster is a smell — they are the same class and should say so.
+ */
+export const RECURRENCE_CLUSTERS = [
+  {
+    id: 'copies-a-claim',
+    name: 'A partner copies a claim and goes stale when the source changes',
+    lessonKey:
+      'implement-suggestion-lessons::a-mechanism-clause-you-correct-in-the-pr-body-must-be-corrected-in-every-doc-that-copies-it',
+    why: 'Some surface — a mirrored module, a generated artifact, a doc paragraph — restates a claim it does not own. Changing the origin does not change the copy, and nothing in the edit itself points at the copy.',
+  },
+  {
+    id: 'sibling-set',
+    name: 'A set-enumerating surface gains a hole when a member is added or moved',
+    lessonKey: 'aw-lessons::docs-drift-grep-must-search-names-not-invocation',
+    why: 'Several surfaces enumerate a set (every command, every docs page, every mirrored file). Adding or moving a member leaves each enumeration silently incomplete, and a grep for the invocation rather than the name misses them.',
+  },
+];
+
+const BY_ID = new Map(RECURRENCE_CLUSTERS.map((cl) => [cl.id, cl]));
+const BY_LESSON_KEY = new Map(RECURRENCE_CLUSTERS.map((cl) => [cl.lessonKey, cl]));
+
+/** The cluster with this id, or null. Total: an unknown id is not an error. */
+export function clusterById(id) {
+  if (typeof id !== 'string' || !id) return null;
+  return BY_ID.get(id) ?? null;
+}
+
+/**
+ * The cluster that owns this lesson key, or null. Lets an entry that still
+ * carries a bare `lessonKey` (rather than a `cluster` id) resolve to its class,
+ * so the two forms coexist during the migration.
+ */
+export function clusterForLessonKey(lessonKey) {
+  if (typeof lessonKey !== 'string' || !lessonKey) return null;
+  return BY_LESSON_KEY.get(lessonKey) ?? null;
+}
+
+/**
+ * Resolve an entry's cluster from either form — an explicit `cluster` id wins,
+ * a bare `lessonKey` falls back to reverse lookup. Returns null when the entry
+ * belongs to no known class, which is legal but worth reporting: an entry with
+ * no cluster is a one-off, and a one-off is weak evidence for a check.
+ */
+export function clusterForEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  return clusterById(entry.cluster) ?? clusterForLessonKey(entry.lessonKey);
+}
+
+/**
+ * The lesson key an entry should cite: its own explicit `lessonKey` if it has
+ * one, otherwise its cluster's canonical key.
+ */
+export function lessonKeyForEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  if (typeof entry.lessonKey === 'string' && entry.lessonKey) return entry.lessonKey;
+  return clusterForEntry(entry)?.lessonKey ?? null;
+}
+
+/** Every map entry belonging to a cluster, by id. Order preserved. */
+export function clusterMembers(clusterId, map = []) {
+  if (!Array.isArray(map)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of map) {
+    if (clusterForEntry(entry)?.id !== clusterId) continue;
+    if (!entry.id || seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    out.push(entry.id);
+  }
+  return out;
+}
+
+/**
+ * The join to `dedupe`: does a group of memory keys (a dedupe cluster's
+ * members) already belong to a NAMED recurrence class? A member's `key`
+ * resolves to a class when it equals that class's canonical `lessonKey` or
+ * appears in its `sourceKeys` — the other sightings the class is known to
+ * subsume.
+ *
+ * This is a stronger signal than lexical similarity alone: a dedupe cluster
+ * that resolves here isn't just "these look alike", it's "this is (at least
+ * partly) another sighting of a class we already named and can cite."
+ *
+ * `pure: true` only when EVERY member resolves to the SAME single class — the
+ * strongest case, where merging under the class's canonical key loses no
+ * stragglers. A mixed match (some members resolve, some don't, or they split
+ * across classes) still reports the majority class via `matched`, so a
+ * partial hit isn't silently discarded — ties break by registry order.
+ *
+ * Total: no members, or no member resolving to any class, returns the null
+ * shape rather than throwing or returning undefined fields.
+ */
+export function resolveRecurrenceClass(members = [], clusters = RECURRENCE_CLUSTERS) {
+  const list = Array.isArray(members) ? members : [];
+  const counts = new Map();
+  const matched = [];
+  for (const m of list) {
+    const key = m?.key;
+    if (typeof key !== 'string' || !key) continue;
+    for (const cl of clusters) {
+      const sourceKeys = Array.isArray(cl.sourceKeys) ? cl.sourceKeys : [];
+      if (key !== cl.lessonKey && !sourceKeys.includes(key)) continue;
+      matched.push(key);
+      counts.set(cl.id, (counts.get(cl.id) ?? 0) + 1);
+      break;
+    }
+  }
+  if (matched.length === 0) return { classId: null, className: null, matched: [], pure: false };
+
+  let bestId = null;
+  let bestCount = -1;
+  for (const cl of clusters) {
+    const n = counts.get(cl.id) ?? 0;
+    if (n > bestCount) {
+      bestCount = n;
+      bestId = cl.id;
+    }
+  }
+  const best = clusters.find((cl) => cl.id === bestId) ?? null;
+  const pure = matched.length === list.length && counts.size === 1;
+  return { classId: best?.id ?? null, className: best?.name ?? null, matched, pure };
+}