@lorekit/cli 1.55.2 → 1.56.0

package/README.md

@@ -443,6 +443,57 @@ coincidental overlaps. Any pair scoring at or above `--threshold` links (transit
 into one cluster; only clusters of 2+ members are reported, each with a similarity
 range. Cross-**store** divergence is `diff`'s job; `dedupe` looks within a store.
 
+### `lorekit obligations`
+
+Check a changed-file set against the **Surface-Partner Map** — a declarative
+registry of known, path-keyed file partnerships (a mirrored module, a doc that
+copies a claim, a generated artifact) mined from existing CI guards — and flag
+any partner the map says the changed-set owes but doesn't contain:
+
+```bash
+lorekit obligations supabase/functions/_shared/audit/audit.ts        # positionals
+lorekit obligations --files packages/schemas/src/shared/tool-catalog.ts --json
+git diff --name-only origin/main... | lorekit obligations --strict   # from a real diff
+```
+
+This is a machine version of a recurring review finding: a fix to one surface
+leaves its partner stale because the lessons documenting the partnership are
+retrieved lexically (full-text search + recency) and rarely surface at edit
+time for the exact file just touched. Each matched entry prints its obliged
+partner files/actions, marks each as met (✓) or unmet (!), and cites the
+memory `lessonKey` the partnership encodes.
+
+An `obliges` element is a required partner path/glob, a `run:<action>`
+advisory that is always reported but never gates `--strict` (some
+partnerships are "regenerate this," not "edit this file"), or an "any of"
+group satisfied by whichever of several candidates is present. `{name}` (or
+`**/{name}`) in a `match`/`obliges` glob binds a mirrored module's relative
+path (directories + stem, extension stripped), for the (rare) case where a
+partner's path genuinely IS a predictable function of the source's, so one
+entry covers every module instead of needing one per file.
+
+The `edge-mirror`/`edge-mirror-core` entries (mcp-core ↔ the self-contained
+Deno edge mirrors) do NOT use that glob mechanism: an edge mirror doesn't
+reliably preserve mcp-core's directory structure (it may flatten or rename
+it), so a symmetric-path reconstruction false-positives on exactly those
+pairs. Instead, both entries are generated — one row per pair — from
+`src/shared/mirror-pairs.mjs`, the single-source inventory
+`packages/mcp-core/src/edge/edge-parity.spec.ts` also reads for its
+byte-comparison drift guard, so the spec and this command can never disagree
+about which files mirror which.
+
+**Cwd-independent by design**: it matches the path STRINGS it is given
+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
+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 link` (alias `url`)
 
 Print a shareable **dashboard deep-link URL** to stdout — nothing else, so it
@@ -996,12 +1047,14 @@ 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` / `link` / `purge` / `purge-expired`) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `obligations` / `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`) |
 | `--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

@@ -74,6 +74,14 @@ ${c.bold('Commands')}
   dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
+  obligations Check a changed-file set against the Surface-Partner Map: known,
+              path-keyed file partnerships (a mirrored module, a doc that
+              copies a claim, a generated artifact) mined from existing CI
+              guards. Prints each matched partnership's obliged partner
+              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).
   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
@@ -111,9 +119,11 @@ ${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 / link)
+      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe / obligations / link)
       --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)
       --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)
@@ -566,6 +576,41 @@ ${c.bold('Examples')}
   npx @lorekit/cli dedupe
   npx @lorekit/cli dedupe --threshold 0.6 --json
   npx @lorekit/cli dedupe --cluster-by-key "(pr\\d+-\\d+)" --json
+`,
+  obligations: `${c.bold('lorekit obligations')} — check a changed-file set against the Surface-Partner Map
+
+${c.bold('Usage')}
+  npx @lorekit/cli obligations <path>... [options]
+  npx @lorekit/cli obligations --files <path>... [options]
+  git diff --name-only | npx @lorekit/cli obligations [options]
+
+Checks a changed-file set against a declarative registry of known, path-keyed
+file partnerships (a mirrored module, a doc that copies a claim, a generated
+artifact) mined from existing CI guards — a machine version of the recurring
+review finding "you fixed one surface and left its partner stale." For each
+matched partnership it prints the obliged partner files/actions and flags any
+partner NOT in the given changed-set, citing the memory lesson the
+partnership encodes.
+
+Cwd-INDEPENDENT: it matches the path STRINGS it is given against the map — it
+never reads the filesystem or resolves scope from the current directory, so
+the changed-set can come from anywhere (a git diff, a PR file list, by hand).
+
+The changed-set is positionals unioned with ${c.cyan('--files')} (its single-value
+form — extra paths after it fall through as positionals); when neither is
+given, it falls back to stdin lines (newline-separated, trimmed, non-empty),
+read only when stdin is piped.
+
+${c.bold('Options')}
+      --files <path>...   Changed files to check (also: positionals, stdin)
+      --strict            Exit non-zero when any path obligation is unmet
+                          (an advisory run: action never gates this)
+      --json              Machine-readable output ({ files, matched, unmet, ok })
+
+${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
 `,
   link: `${c.bold('lorekit link')} — print a shareable dashboard deep-link URL ${c.dim('(alias: url)')}
 
@@ -835,6 +880,8 @@ 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',
+  // `obligations`
+  'files', 'strict',
 ];
 
 async function main() {
@@ -847,7 +894,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'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'strict'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/src/commands/mcp-server.mjs

@@ -365,7 +365,7 @@ export function advertise(dispatch) {
       if (!def) {
         throw new Error(
           `mcp-server dispatches "${name}", which the tool catalog does not declare. `
-          + 'Add it to packages/schemas/src/shared/tool-catalog.ts (and regenerate: node scripts/gen-surfaces.mjs).',
+          + 'Add it to packages/schemas/src/shared/tool-catalog.ts (and regenerate: node scripts/codegen/gen-surfaces.mjs).',
         );
       }
       return def;

package/src/commands/obligations.mjs

@@ -0,0 +1,135 @@
+// `lorekit obligations` — check a changed-file set against the Surface-Partner
+// Map (`../shared/obligations-map.mjs`) and print any partner surface a known
+// partnership obliges that is NOT itself in the changed set ("you forgot to
+// sweep X"), citing the memory lesson the partnership encodes.
+//
+// This is a machine version of a recurring `dash0-dev` review finding: a fix
+// to one surface leaves its partner stale because the lessons documenting the
+// partnership are retrieved lexically and rarely surface at edit time for the
+// exact file just touched. Slice 1 is a standalone CLI check — no hook
+// wiring, no server changes (see the plan's Out-of-scope section).
+//
+// Cwd-INDEPENDENT by design (`cli-bash-cwd-resets-to-repo-root-each-call`):
+// it matches the path STRINGS it is given against the map; it never reads the
+// filesystem or resolves scope from the current directory, so it works the
+// same regardless of where it is invoked from as long as the paths given are
+// repo-relative.
+//
+// Changed-set resolution — positionals and `--files` are UNIONED (so both a
+// bare list and the flag form work together, and `--files a b c` composes
+// naturally: the parser's single-value form takes `a` as the flag's value and
+// leaves `b`/`c` as positionals); stdin is read only as a FALLBACK, when
+// NEITHER produced anything — the same flag → positional → stdin precedence
+// `write.mjs`'s value resolution uses. This is a deliberate narrowing from a
+// flat three-way union: reading stdin unconditionally means every invocation
+// that already named its files explicitly still blocks on stdin closing,
+// which is surprising for a caller that piped nothing, and turns any
+// in-process call (e.g. this command under `node:test`, invoked directly
+// rather than spawned) into a hang, since the test runner's own stdin never
+// reaches EOF. De-duplicated, first-seen order preserved.
+//
+//   1. positionals after the command token (`obligations <path> <path> …`)
+//      unioned with `--files <path>`
+//   2. stdin lines (trimmed, non-empty) — read ONLY when (1) is empty and
+//      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.
+import process from 'node:process';
+import { log, heading, c } from '../shared/util.mjs';
+import { checkObligations } from '../shared/obligations-pure.mjs';
+import { SURFACE_PARTNER_MAP } from '../shared/obligations-map.mjs';
+
+// Read stdin line-by-line, trimmed, non-empty. Resolves to [] when stdin IS a
+// TTY (no pipe) — the same "no pipe, no read" convention `write.mjs` uses.
+function readStdinLines() {
+  if (process.stdin.isTTY) return Promise.resolve([]);
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.on('data', (d) => chunks.push(d));
+    process.stdin.on('end', () => {
+      const lines = Buffer.concat(chunks)
+        .toString('utf8')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+      resolve(lines);
+    });
+    process.stdin.resume();
+  });
+}
+
+// The resolved changed-set: (positionals ∪ --files), falling back to stdin
+// only when that union is empty. De-duplicated, first-seen order preserved.
+async function resolveChangedFiles(args) {
+  const positionals = args._.slice(1).filter((p) => typeof p === 'string' && p);
+  const flagged = typeof args.files === 'string' && args.files ? [args.files] : [];
+  const named = dedupe([...positionals, ...flagged]);
+  if (named.length > 0) return named;
+  return dedupe(await readStdinLines());
+}
+
+function dedupe(list) {
+  const seen = new Set();
+  const out = [];
+  for (const f of list) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      out.push(f);
+    }
+  }
+  return out;
+}
+
+export async function obligations(args) {
+  const changedFiles = await resolveChangedFiles(args);
+  const strict = Boolean(args.strict);
+  const result = checkObligations({ changedFiles, map: SURFACE_PARTNER_MAP });
+
+  if (args.json) {
+    log(JSON.stringify({ ...result, strict }, null, 2));
+  } else {
+    render(result, changedFiles);
+  }
+
+  return {
+    exitCode: strict && result.unmet > 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.strict': strict,
+  };
+}
+
+function render(result, changedFiles) {
+  heading('LoreKit obligations');
+  log(`  files: ${c.dim(changedFiles.length ? changedFiles.join(', ') : '(none given)')}`);
+
+  if (result.matched.length === 0) {
+    log('');
+    log(`  ${c.dim('no known surface-partner obligations for the given changed-set')}`);
+    log('');
+    return;
+  }
+
+  for (const entry of result.matched) {
+    log('');
+    log(`  ${c.bold(entry.id)}${entry.guard ? c.dim(`  (guard: ${entry.guard})`) : ''}`);
+    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('!');
+      const suffix = o.kind === 'action' ? c.dim(' (advisory — run this yourself)') : '';
+      log(`    ${mark} ${o.target}${suffix}`);
+    }
+    log(`    ${c.dim(`cites: ${entry.lessonKey}`)}`);
+  }
+
+  log('');
+  if (result.unmet === 0) {
+    log(`  ${c.green('✓')} every known path obligation is satisfied by the given changed-set`);
+  } else {
+    const plural = result.unmet === 1 ? '' : 's';
+    log(`  ${c.yellow('!')} ${result.unmet} unmet obligation${plural} — sweep the partner${plural} above`);
+  }
+  log('');
+}

package/src/commands/purge.mjs

@@ -19,7 +19,7 @@
 //    `--json`). An agent loop must not be able to trigger one by omission.
 //
 // 3. A SCOPED KEY IS REFUSED BY THE SERVER, and that refusal is passed through
-//    verbatim. `_shared/account-wide-tools.ts` refuses these two operations for
+//    verbatim. `_shared/auth/account-wide-tools.ts` refuses these two operations for
 //    any token carrying a scope allowlist — a key narrowed to one repo has no
 //    business sweeping the whole account. The CLI makes exactly one request and
 //    reports the server's answer; it never retries, never splits the sweep and

package/src/commands/show.mjs

@@ -10,7 +10,10 @@
 //                            you can copy-paste a key directly from list output)
 //   show <scope> <key>     — the explicit two-positional form
 //   show --scope <s> --key <k>
-//                          — flags win; the only way to name a key containing `::`
+//                          — flags win; an explicit override that skips the `::`
+//                            split (the shorthand already carries a namespaced
+//                            key, since the split lands at the first valid-scope
+//                            prefix — see `resolveScopeArg`)
 //
 // Uses each store's real `read({scope, key})` method (both stores expose it),
 // not a filtered `list` — a single-record lookup is what `read` is for, and it
@@ -60,8 +63,9 @@ export async function show(args) {
   // Positional shapes (all resolved by the shared, validity-gated parser):
   //   show <scope::key>            — canonical shorthand, mirrors `list` output
   //   show <scope> <key>           — explicit two-positional form
-  //   show --scope <s> --key <k>   — flags win; the escape hatch for a key
-  //                                  containing `::`
+  //   show --scope <s> --key <k>   — flags win; an explicit override that skips
+  //                                  the `::` split (the shorthand handles a
+  //                                  namespaced key on its own now)
   const positionals = args._.slice(1);
   const { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
     scope: args.scope,

package/src/commands.mjs

@@ -47,6 +47,7 @@ import { diff } from './commands/diff.mjs';
 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 { link } from './commands/link.mjs';
 import { hook } from './commands/hook.mjs';
 import { migrate } from './commands/migrate.mjs';
@@ -77,6 +78,7 @@ export const COMMANDS = [
   { name: 'tree', run: tree, traced: true, strictFlags: true, native: 'resolves the scope hierarchy for a directory', aliases: ['resolve'] },
   { 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: '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/lessons-pure.mjs

@@ -122,23 +122,29 @@ export function isScopeString(s) {
 // Split a single `<scope>::<key>` argument, or fall back to treating the whole
 // argument as a scope.
 //
-// The rule: split at the LAST `::` and take it as `<scope>::<key>` ONLY when the
-// left side is itself a COMPLETE valid scope — otherwise the whole arg is the
-// scope. Splitting on the last `::` (not the first) keeps a multi-segment scope
-// whole (`repo::owner/name::key` → scope `repo::owner/name`, key `key`); gating
-// on a valid left side means a bare `repo::owner/name` is NOT mis-split, because
-// its left part `repo` is not a valid scope. This is the fix for the prior
-// first-`::` split, which turned `link repo::acme/widget` into scope="repo" plus
-// a bogus `acme/widget` key — breaking the shorthand for EVERY non-`global`
-// scope. A malformed arg falls through to the scope, never a fabricated key.
+// The rule: scan the `::` boundaries left-to-right and split at the FIRST one
+// whose left side is a COMPLETE valid scope — otherwise the whole arg is the
+// scope. Because `::` is RESERVED as the segment separator (no scope segment may
+// contain it, enforced by `scopeIssue`), no valid scope is a `::`-boundary
+// prefix of another, so the earliest valid-scope prefix is unambiguously THE
+// scope and everything after it is the key — even a key that itself contains
+// `::` (a namespaced key like `implement-suggestion-lessons::documenting-…`).
+//
+// This first-valid scan superseded a plain last-`::` split, which broke exactly
+// that case: `global::foo-lessons::bar` split at the last `::` gave the left
+// side `global::foo-lessons`, not a valid scope, so the whole arg fell through
+// to the scope and `scopeIssue` rejected it. Gating on a valid left side is what
+// keeps a bare `repo::owner/name` from mis-splitting (its `repo` prefix is not a
+// valid scope) and a multi-segment scope whole (`branch::o/n::main::key` → scope
+// `branch::o/n::main`, key `key`, since the shorter prefixes are all invalid). A
+// malformed arg falls through to the scope, never a fabricated key.
 //
 // `isScope` is injected rather than closed over so the module stays trivially
 // testable with a stub predicate; callers pass `isScopeString`.
 export function resolveScopeArg(arg, isScope = isScopeString) {
   const s = typeof arg === 'string' ? arg.trim() : '';
   if (!s) return { scope: null, key: null };
-  const idx = s.lastIndexOf('::');
-  if (idx !== -1) {
+  for (let idx = s.indexOf('::'); idx !== -1; idx = s.indexOf('::', idx + 2)) {
     const left = s.slice(0, idx).trim();
     const right = s.slice(idx + 2).trim();
     if (right && isScope(left)) return { scope: left, key: right };

package/src/shared/mcp.mjs

@@ -159,7 +159,7 @@ export function mcpToRestBase(mcpEndpointUrl) {
 /**
  * Normalise a client-supplied usage correlation id (a PR ref, session id, or CI
  * job id). Bounded + charset-restricted to match the server's `parseCorrelationId`
- * (supabase/functions/_shared/usage-stats.ts); returns null for empty/over-long/
+ * (supabase/functions/_shared/telemetry/usage-stats.ts); returns null for empty/over-long/
  * out-of-charset input so a bad value is simply not sent. Zero-dep (the CLI does
  * not import mcp-core), so the small regex is duplicated intentionally.
  */

package/src/shared/mirror-pairs.mjs

@@ -0,0 +1,86 @@
+// The single-source inventory of known mcp-core ↔ edge (Deno) mirror pairs.
+//
+// TWO consumers read this ONE list instead of each keeping (or reconstructing)
+// its own:
+//   - `packages/mcp-core/src/edge/edge-parity.spec.ts` — loads it by URL (the
+//     `lesson-rank-parity.spec.ts` cross-runtime pattern: this is a plain
+//     `.mjs` package outside the vitest project's tsconfig) and runs its
+//     byte-for-byte drift guard over every `driftChecked: true` pair.
+//   - `packages/cli/src/shared/obligations-map.mjs` — generates the
+//     `edge-mirror` / `edge-mirror-core` Surface-Partner Map rows from EVERY
+//     pair here (`driftChecked` included), so `lorekit obligations` reports
+//     the pair's ACTUAL partner.
+//
+// Why a flat enumerated list rather than a glob + `{name}` substitution: an
+// edge mirror does not always preserve mcp-core's directory structure — e.g.
+// `packages/mcp-core/src/auth/auth-token.ts` mirrors the FLAT
+// `supabase/functions/mcp/auth-token.ts`, not
+// `supabase/functions/mcp/auth/auth-token.ts`. A glob that assumes the same
+// relative subpath on both sides reconstructs the WRONG partner path for
+// every such flatten/rename and reports a real, present mirror as
+// chronically unmet. Enumerating each pair's exact core/edge path from one
+// inventory has no such assumption to violate.
+//
+// Every path is REPO-RELATIVE (not relative to this file), so both consumers
+// use it directly: `edge-parity.spec.ts` joins it against the repo root,
+// and `obligations-map.mjs`/`checkObligations` match it against changed-file
+// path strings verbatim.
+//
+// `driftChecked: true`  — both files are import-free, so `edge-parity.spec.ts`
+//                          also runs its whole-file byte comparison over the
+//                          pair (stripped of comments/blank lines).
+// `driftChecked: false` — a REAL partner for `lorekit obligations` purposes,
+//                          but excluded from that byte comparison because the
+//                          edge copy is not import-free (it carries Deno-only
+//                          types/APIs the mcp-core copy has no counterpart
+//                          for — see each entry's note below).
+//
+// Deliberately NOT included: `supabase/functions/mcp/cursor.ts` ↔
+// `supabase/functions/_shared/api/paginate.ts` (guarded by edge-parity.spec.ts's
+// separate "cursor mirror parity" block). Both sides live under
+// `supabase/functions/`, so it is an edge↔edge mirror, not the mcp-core↔edge
+// partnership this inventory and the `edge-mirror`/`edge-mirror-core` map
+// entries model.
+export const mirrorPairs = [
+  { core: 'packages/mcp-core/src/auth/auth-token.ts', edge: 'supabase/functions/mcp/auth-token.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/limits/created-at.ts', edge: 'supabase/functions/_shared/limits/created-at.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/limits/ttl.ts', edge: 'supabase/functions/mcp/ttl.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/limits/ttl-defaults.ts', edge: 'supabase/functions/mcp/ttl-defaults.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/provenance/origin.ts', edge: 'supabase/functions/_shared/provenance/origin.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/webhook/webhook-secret-select.ts', edge: 'supabase/functions/mcp/webhook-secret-select.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/auth/tenant-scope.ts', edge: 'supabase/functions/_shared/auth/tenant-scope.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/auth/org-permissions.ts', edge: 'supabase/functions/mcp/org-permissions.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/webhook/webhook-installation.ts', edge: 'supabase/functions/mcp/webhook-installation.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/webhook/github-app-jwt.ts', edge: 'supabase/functions/mcp/github-app-jwt.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/telemetry/trace-context.ts', edge: 'supabase/functions/_shared/telemetry/trace-context.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/rest/rest-tool-name.ts', edge: 'supabase/functions/_shared/rest/rest-tool-name.ts', driftChecked: true },
+  // Has a SECOND, cross-LANGUAGE twin no byte comparison can cover — the
+  // CLI's own `lessons-pure.mjs` — guarded behaviourally by
+  // `lesson-rank-parity.spec.ts` instead.
+  { core: 'packages/mcp-core/src/ranking/lesson-rank.ts', edge: 'supabase/functions/_shared/ranking/lesson-rank.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/ranking/outcome-signal.ts', edge: 'supabase/functions/_shared/ranking/outcome-signal.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/provenance/embedding.ts', edge: 'supabase/functions/_shared/embedding/embedding.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/audit/rest-audit-actor.ts', edge: 'supabase/functions/_shared/audit/rest-audit-actor.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/rest/rest-response-outcome.ts', edge: 'supabase/functions/_shared/rest/rest-response-outcome.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/limits/dry-run.ts', edge: 'supabase/functions/_shared/limits/dry-run.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/telemetry/usage-stats.ts', edge: 'supabase/functions/_shared/telemetry/usage-stats.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/limits/expiring-window.ts', edge: 'supabase/functions/_shared/limits/expiring-window.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/rest/cors-origins.ts', edge: 'supabase/functions/_shared/api/cors-origins.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/scope/scope-type-attribute.ts', edge: 'supabase/functions/_shared/scope/scope-type-attribute.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/auth/account-wide-tools.ts', edge: 'supabase/functions/_shared/auth/account-wide-tools.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/telemetry/io-ledger.ts', edge: 'supabase/functions/_shared/telemetry/io-ledger.ts', driftChecked: true },
+  { core: 'packages/mcp-core/src/telemetry/db-query-metrics.ts', edge: 'supabase/functions/_shared/telemetry/db-query-metrics.ts', driftChecked: true },
+  // Excluded from the byte-comparison drift check: the edge copy types the
+  // client as `ReturnType<typeof createClient>` off an `npm:` specifier where
+  // mcp-core imports a typed `SupabaseClient`, and additionally carries
+  // `recordAuditDeferred` (a Deno-only `EdgeRuntime.waitUntil` API with no
+  // mcp-core counterpart), so a whole-file comparison does not apply. Still a
+  // real partner — this is the AC-1 example.
+  { core: 'packages/mcp-core/src/audit/audit.ts', edge: 'supabase/functions/_shared/audit/audit.ts', driftChecked: false },
+  // Excluded from the byte-comparison drift check for the same reason as
+  // `limits.ts` generally (see edge-parity.spec.ts): the edge copy pulls in
+  // Deno-specific imports, so a whole-file source comparison does not apply.
+  // Its shared pure logic is exercised behaviourally by `limits.spec.ts` on
+  // the mcp-core copy. Still a real partner.
+  { core: 'packages/mcp-core/src/limits/limits.ts', edge: 'supabase/functions/mcp/limits.ts', driftChecked: false },
+];

package/src/shared/obligations-map.mjs

@@ -0,0 +1,154 @@
+// The Surface-Partner Map — a declarative registry of known, path-keyed file
+// partnerships in this repo. This is slice 1 of the fix for a structural
+// retrieval leak the `dash0-dev` review bot repeatedly flags: a fix to one
+// surface (a mirrored module, a doc that copies a claim, a generated artifact,
+// a required test assertion) leaves its PARTNER surface stale, because the
+// lessons documenting each partnership are retrieved lexically (FTS +
+// recency) and rarely surface at edit time for the exact file just touched.
+//
+// Every entry here is SEEDED from an existing, real CI guard — it duplicates
+// no enforcement, it just makes the partnership visible to `lorekit
+// obligations` (see `../commands/obligations.mjs`) BEFORE the guard runs, so
+// a human or agent can sweep the partner in the same commit instead of
+// discovering the gap in review. `guard` names that real spec/script per
+// entry; entries with no automated guard (`perf-index`, `error-code-doc`) say
+// so explicitly rather than implying one exists.
+//
+// Entry schema:
+//   {
+//     id: string,               // stable identifier
+//     match: string|string[],   // repo-relative glob(s); a `re:` prefix is
+//                                // used as a verbatim RegExp; `**/{name}` or
+//                                // `{name}` binds the matched module's
+//                                // relative path (dirs + stem, extension
+//                                // stripped) for reuse in `obliges`
+//     obliges: Array<string | string[]>,
+//                                // each element is EITHER a required partner
+//                                // path/glob (may reuse `{name}`), a
+//                                // `run:<action>` advisory (never gates
+//                                // --strict), OR an array of alternative
+//                                // paths satisfied by ANY ONE of them (used
+//                                // when a name-derived module's real partner
+//                                // could live under either of two sibling
+//                                // directories)
+//     lessonKey: string,        // canonical memory key to cite
+//     guard?: string,           // the existing CI spec/script that enforces
+//                                // this partnership, if any
+//     note?: string,            // why this entry exists / its limitations
+//   }
+//
+// See `obligations-pure.mjs` for the matcher and the exact `{name}` grammar.
+//
+// The `edge-mirror` / `edge-mirror-core` rows below are a special case: they
+// are GENERATED, one pair of rows per entry in `mirrorPairs`
+// (`./mirror-pairs.mjs`, the single-source inventory shared with
+// `packages/mcp-core/src/edge/edge-parity.spec.ts`), rather than hand-authored
+// with a `{name}`-substituting glob. A glob assuming the edge copy mirrors
+// mcp-core's directory structure false-positives whenever a real mirror
+// flattens or renames it (e.g. `packages/mcp-core/src/auth/auth-token.ts` ↔
+// the FLAT `supabase/functions/mcp/auth-token.ts`) — the exact-path
+// reconstruction it would need to get right is simply not derivable from the
+// two paths alone. Enumerating each KNOWN pair's real partner has no such
+// assumption to violate. `checkObligations` already merges every map entry
+// that shares an `id` into one reported bucket (see `obligations-pure.mjs`'s
+// `byId` merge in the matcher), so the many generated rows below still
+// surface as the two logical `edge-mirror` / `edge-mirror-core` entries.
+
+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
+// module-level note above for why this replaces a `{name}`-templated glob.
+const EDGE_MIRROR_ENTRIES = mirrorPairs.flatMap(({ core, edge }) => [
+  {
+    id: 'edge-mirror',
+    match: edge,
+    obliges: [core],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    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',
+    match: core,
+    obliges: [edge],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    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.',
+  },
+]);
+
+export const SURFACE_PARTNER_MAP = [
+  ...EDGE_MIRROR_ENTRIES,
+  {
+    id: 'tool-catalog',
+    match: 'packages/schemas/src/shared/tool-catalog.ts',
+    obliges: [
+      'supabase/functions/mcp/tool-dispatch.generated.ts',
+      'packages/cli/src/surfaces.generated.mjs',
+      'packages/web/public/llms.txt',
+      'run:pnpm nx generate:llms schemas',
+    ],
+    lessonKey: COPIES_A_CLAIM_LESSON,
+    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',
+    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,
+    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',
+    match: 're:^packages/web/src/content/docs/[^/]+\\.mdx$',
+    obliges: ['packages/web/src/lib/docs/sections.ts'],
+    lessonKey: SIBLING_SET_LESSON,
+    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',
+    match: 'packages/cli/skill/**',
+    obliges: ['run:node scripts/codegen/sync-plugin-skill.mjs', 'plugins/lorekit-claude/skills/**'],
+    lessonKey: SIBLING_SET_LESSON,
+    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: 'perf-index',
+    match: 're:^supabase/migrations/.*index.*\\.sql$',
+    obliges: ['supabase/tests/migrations.test.sql'],
+    lessonKey: SIBLING_SET_LESSON,
+    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',
+    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,
+    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).',
+  },
+];

package/src/shared/obligations-pure.mjs

@@ -0,0 +1,246 @@
+// Pure, DEPENDENCY-FREE matcher for the Surface-Partner Map (`obligations-map.mjs`).
+//
+// The problem this solves: a fix to one surface (a mirrored module, a doc that
+// copies a claim, a generated artifact) routinely leaves its PARTNER surface
+// stale, because the ~45 memory lessons documenting each known partnership are
+// retrieved lexically (FTS + recency) and never surface at edit time for a
+// specific file. Since the recurrences are known, PATH-KEYED file
+// partnerships, a deterministic path-keyed check beats search — this module is
+// that check.
+//
+// Zero imports on purpose (mirrors `lessons-pure.mjs`) and NEVER touches the
+// filesystem or `process.cwd()` — see the module-level note in
+// `obligations-map.mjs`. It matches the path STRINGS it is given against the
+// map; the IO shell (`commands/obligations.mjs`) resolves those strings from
+// argv/stdin.
+//
+// ── the `{name}` placeholder ────────────────────────────────────────────────
+//
+// A `match`/`obliges` glob may contain the literal token `{name}` to bind the
+// module's relative path (directories + file stem, extension stripped) so a
+// generic partnership (`edge-mirror`) doesn't need one map entry per module.
+// The token is recognised in two shapes:
+//
+//   `**/{name}`  — ONE capturing group spanning zero or more path segments
+//                  AND the final stem, e.g. `src/**/{name}.ts` captures
+//                  `audit/audit` out of `src/audit/audit.ts`, for reuse in a
+//                  partner pattern's own `**/{name}` slot. This ONLY works
+//                  when the partner's directory structure is a predictable
+//                  function of the source's — e.g. `docs-section`'s
+//                  `sections.ts` entry needs no name at all, so it's not used
+//                  there either. It is NOT used by the seed map's
+//                  `edge-mirror`/`edge-mirror-core` entries (see
+//                  `obligations-map.mjs`): a real edge (Deno) mirror does not
+//                  reliably preserve mcp-core's directory structure — it may
+//                  flatten or rename it — so those two entries instead
+//                  enumerate every KNOWN pair's exact partner from a
+//                  single-source inventory (`mirror-pairs.mjs`) rather than
+//                  reconstruct a partner path via substitution. The token
+//                  remains available here as a general primitive for any
+//                  future map entry whose partner path genuinely IS a
+//                  predictable function of the source's.
+//   `{name}`     — a single-segment capturing group (no preceding `**/`) for
+//                  a flat `{name}.ext` match with no directory component.
+//
+// `stemOf` (below) is the simpler, general-purpose primitive — a plain
+// basename-without-extension — exported for standalone use and unit testing.
+
+export const RUN_PREFIX = 'run:';
+export const REGEX_PREFIX = 're:';
+
+const NAME_TOKEN = '{name}';
+const DIR_NAME_TOKEN = `**/${NAME_TOKEN}`;
+
+// Basename of `path`, extension stripped. A leading-dot file (`.env`) is its
+// own stem (no extension to strip) rather than an empty string.
+export function stemOf(path) {
+  const base = String(path ?? '').split('/').pop() ?? '';
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+// Escape one character for literal inclusion in a RegExp source string.
+function escapeChar(ch) {
+  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+
+// Compile a single glob/regex pattern string into `{ regex, capturesName }`.
+// `re:`-prefixed patterns are used verbatim (already anchored by the author,
+// per the seed map's `docs-section`/`perf-index` entries) and never capture a
+// name. Anything else is compiled token-by-token: `**/{name}` and bare
+// `{name}` become the ONE capturing group a pattern may have, `**` becomes
+// `.*`, `*` becomes `[^/]*`, and every other character is escaped literally.
+// Returns null for a non-string / empty pattern, never throws.
+export function compilePattern(pattern) {
+  if (typeof pattern !== 'string' || !pattern) return null;
+  if (pattern.startsWith(REGEX_PREFIX)) {
+    try {
+      return { regex: new RegExp(pattern.slice(REGEX_PREFIX.length)), capturesName: false };
+    } catch {
+      return null;
+    }
+  }
+  let src = '';
+  let capturesName = false;
+  let i = 0;
+  while (i < pattern.length) {
+    if (pattern.startsWith(DIR_NAME_TOKEN, i)) {
+      src += '(.+)';
+      capturesName = true;
+      i += DIR_NAME_TOKEN.length;
+    } else if (pattern.startsWith(NAME_TOKEN, i)) {
+      src += '([^/]+)';
+      capturesName = true;
+      i += NAME_TOKEN.length;
+    } else if (pattern.startsWith('**', i)) {
+      src += '.*';
+      i += 2;
+    } else if (pattern[i] === '*') {
+      src += '[^/]*';
+      i += 1;
+    } else {
+      src += escapeChar(pattern[i]);
+      i += 1;
+    }
+  }
+  return { regex: new RegExp(`^${src}$`), capturesName };
+}
+
+// Compile `glob` into a plain, non-capturing-aware `RegExp` — the general
+// membership test used both to check whether a changed file satisfies a
+// (post-substitution) oblige target, and by tests exercising the glob syntax
+// in isolation. Same token grammar as `compilePattern`; a `{name}` left
+// unsubstituted (never expected once `checkObligations` has run) simply
+// compiles to its capturing form, still usable as a plain matcher.
+export function globToRegExp(glob) {
+  return compilePattern(glob)?.regex ?? null;
+}
+
+// Replace the pattern's name placeholder with a captured value. `**/{name}`
+// is replaced as ONE unit (so the substitution reconstructs a full relative
+// path, matching how `compilePattern` captured it); a bare `{name}` is
+// replaced on its own. `name == null` (no capture in the matching `match`
+// pattern) returns `pattern` unchanged — nothing to substitute.
+export function substituteName(pattern, name) {
+  if (name == null || typeof pattern !== 'string') return pattern;
+  if (pattern.includes(DIR_NAME_TOKEN)) return pattern.split(DIR_NAME_TOKEN).join(name);
+  if (pattern.includes(NAME_TOKEN)) return pattern.split(NAME_TOKEN).join(name);
+  return pattern;
+}
+
+// Does `file` satisfy `globPattern` (post-substitution, so no `{name}` token
+// remains, but `**`/`*` wildcards may)? Compiles and tests in one step; an
+// uncompilable pattern never matches.
+function fileSatisfies(file, globPattern) {
+  const regex = globToRegExp(globPattern);
+  return regex ? regex.test(file) : false;
+}
+
+// Fold one `obliges` element into `bucket` (a `Map<target, row>` keyed by the
+// rendered target string, so repeated matches — several changed files hitting
+// the same entry — dedupe by the concrete, substituted target rather than by
+// raw template).
+//
+// An element is one of:
+//   `run:<action>`        — advisory, `kind:'action'`, `met: null`, never
+//                            gates `--strict`.
+//   a string               — a single required path/glob, `kind:'path'`.
+//   an array of strings    — an "any of" group: the obligation is met if ANY
+//                            candidate is present in `changedFiles` (for a
+//                            partner that could legitimately live in more
+//                            than one place). Rendered as one row whose
+//                            `target` joins every candidate with ` OR `,
+//                            `met` true iff any candidate matches. The seed
+//                            map's `edge-mirror`/`edge-mirror-core` entries do
+//                            NOT use this — see `obligations-map.mjs` — since
+//                            enumerating each known pair's exact partner from
+//                            `mirror-pairs.mjs` needs no "either of" guess.
+// A row already present for the same rendered target has its `met` OR'd in
+// (never downgraded from true to false by a later, differently-named match).
+function addOblige(bucket, rawOblige, name, changedFiles) {
+  if (typeof rawOblige === 'string' && rawOblige.startsWith(RUN_PREFIX)) {
+    if (!bucket.has(rawOblige)) bucket.set(rawOblige, { target: rawOblige, kind: 'action', met: null });
+    return;
+  }
+  const candidates = (Array.isArray(rawOblige) ? rawOblige : [rawOblige])
+    .filter((c) => typeof c === 'string' && c);
+  if (candidates.length === 0) return;
+  const substituted = candidates.map((c) => substituteName(c, name));
+  const met = substituted.some((c) => changedFiles.some((f) => fileSatisfies(f, c)));
+  const target = substituted.join(' OR ');
+  const existing = bucket.get(target);
+  if (existing) existing.met = existing.met || met;
+  else bucket.set(target, { target, kind: 'path', met });
+}
+
+/**
+ * Check a changed-file set against the Surface-Partner Map. For every
+ * `(file, entry)` pair where `file` satisfies one of `entry.match`'s
+ * patterns, the entry is recorded as matched and its `obliges` are resolved
+ * (with `{name}` substituted from whatever the matching pattern captured) and
+ * checked for membership in `changedFiles`. Entries are deduped by `id` — a
+ * file set can hit the same entry via several files, and each contributes its
+ * own name-substituted targets into that one entry's `obliges` list.
+ *
+ * Pure and total: a malformed `map`/`changedFiles` degrades to no matches
+ * rather than throwing.
+ *
+ * Returns `{ files, matched, unmet, ok }` — see `obligations-map.mjs`'s
+ * schema docblock for the shape of each `matched` entry.
+ */
+export function checkObligations({ changedFiles = [], map = [] } = {}) {
+  const files = Array.isArray(changedFiles)
+    ? changedFiles.filter((f) => typeof f === 'string' && f.length > 0)
+    : [];
+  const entries = Array.isArray(map) ? map : [];
+
+  const byId = new Map(); // id -> { id, lessonKey, guard, note, obliges: Map<target, row> }
+
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object' || !entry.id) continue;
+    const patterns = Array.isArray(entry.match) ? entry.match : [entry.match];
+
+    for (const file of files) {
+      let matched = false;
+      let name = null;
+      for (const pattern of patterns) {
+        const compiled = compilePattern(pattern);
+        if (!compiled) continue;
+        const m = compiled.regex.exec(file);
+        if (m) {
+          matched = true;
+          if (compiled.capturesName) name = m[1];
+          break;
+        }
+      }
+      if (!matched) continue;
+
+      let bucket = byId.get(entry.id);
+      if (!bucket) {
+        bucket = {
+          id: entry.id,
+          lessonKey: entry.lessonKey ?? null,
+          guard: entry.guard ?? null,
+          note: entry.note ?? null,
+          obliges: new Map(),
+        };
+        byId.set(entry.id, bucket);
+      }
+      for (const rawOblige of Array.isArray(entry.obliges) ? entry.obliges : []) {
+        addOblige(bucket.obliges, rawOblige, name, files);
+      }
+    }
+  }
+
+  const matched = [...byId.values()].map((b) => ({
+    id: b.id,
+    lessonKey: b.lessonKey,
+    guard: b.guard,
+    note: b.note,
+    obliges: [...b.obliges.values()],
+  }));
+
+  const unmet = matched.reduce((n, e) => n + e.obliges.filter((o) => o.met === false).length, 0);
+
+  return { files, matched, unmet, ok: unmet === 0 };
+}

package/src/surfaces.generated.mjs

@@ -1,6 +1,6 @@
 // GENERATED — do not edit.
 // Source: packages/schemas/src/shared/tool-catalog.ts
-// Regenerate: node scripts/gen-surfaces.mjs
+// Regenerate: node scripts/codegen/gen-surfaces.mjs
 //
 // Edit the catalog's `surfaces` bindings, not this file. `--check` fails CI
 // when the two disagree.

package/src/telemetry/telemetry-token.mjs

@@ -4,7 +4,7 @@
 // source tree and nothing secret is ever committed to git. The release workflow
 // (.github/workflows/release.yml → publish-cli) overwrites this file at publish
 // time from the LOREKIT_TELEMETRY_TOKEN secret via
-// scripts/inject-telemetry-token.mjs, so only the *published npm tarball*
+// scripts/telemetry/inject-telemetry-token.mjs, so only the *published npm tarball*
 // carries the token.
 //
 // The token is public by design once published (anyone can unpack the tarball),

package/src/telemetry/telemetry.mjs

@@ -5,7 +5,7 @@
 // otel.ts): OTLP/JSON over the global fetch (Node 18+), no @opentelemetry/*
 // packages. One span + one counter data point per human-facing command
 // (install / uninstall / doctor / list / search / show / stats / scopes / diff /
-// tree / lint / dedupe / link / migrate), fired to Dash0 so the maintainers can
+// tree / lint / dedupe / obligations / link / migrate), fired to Dash0 so the maintainers can
 // see which commands people actually run.
 //
 // Privacy — this runs on end-users' machines, so it is deliberately narrow:
@@ -183,7 +183,7 @@ export function resolveTelemetryTokenSource(env = process.env) {
   return 'none';
 }
 
-// ── ID + value helpers (mirror _shared/otel.ts) ───────────────────────────────
+// ── ID + value helpers (mirror _shared/telemetry/otel.ts) ───────────────────────────────
 
 export function randHex(bytes) {
   const b = new Uint8Array(bytes);
@@ -236,7 +236,7 @@ export function normalizeHostArch(arch) {
  * the attribute by default. It is emitted ONLY when explicitly overridden via
  * `DEPLOYMENT_ENVIRONMENT` (falling back to `OTEL_DEPLOYMENT_ENVIRONMENT`) — the
  * same single, env-driven knob the edge honours, which the correlated-trace
- * harness (`scripts/emit-correlated-trace.mts`) uses to stamp `test`.
+ * harness (`scripts/telemetry/emit-correlated-trace.mts`) uses to stamp `test`.
  * @param {object} [env]  defaults to process.env
  */
 export function resolveDeploymentEnvironment(env = process.env) {
@@ -709,7 +709,7 @@ export async function meterCommand(command, version, run) {
  * `lint` finding) reports `lorekit.cli.outcome=failure` on a span the exporter
  * emits as STATUS_CODE_OK — never ERROR.
  *
- * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | link | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | obligations | link | migrate
  * @param {object} args     parsed CLI args (read for allow-listed flags only)
  * @param {string} version  CLI version (from package.json)
  * @param {() => Promise<number>} run  the command handler