agentsmesh 0.33.0 → 0.34.0

package/dist/lessons.js

@@ -280,6 +280,23 @@ function todayIso() {
 }
 
 // src/lessons/add-errors.ts
+var EmptyRuleError = class extends Error {
+  code = "EMPTY_RULE";
+  constructor() {
+    super("Lesson rule must not be empty \u2014 pass one imperative sentence.");
+    this.name = "EmptyRuleError";
+  }
+};
+var BroadCommandPatternError = class extends Error {
+  constructor(pattern) {
+    super(
+      `Command pattern ${JSON.stringify(pattern)} matches nearly every command, so it would fire on every recall. Key it on the action instead \u2014 a word-bounded program + subcommand (e.g. "\\bgit commit\\b", "\\brm\\b").`
+    );
+    this.pattern = pattern;
+    this.name = "BroadCommandPatternError";
+  }
+  code = "BROAD_COMMAND_PATTERN";
+};
 var UnknownTopicError = class extends Error {
   constructor(topic) {
     super(`Unknown topic: ${topic}. Pass allowNewTopic + topicSummary to create it.`);
@@ -319,992 +336,1144 @@ var UnrecallableLessonError = class extends Error {
   code = "UNRECALLABLE_LESSON";
 };
 
-// src/lessons/ranking-text.ts
-var K1 = 1.5;
-var B = 0.75;
-var STOP = /* @__PURE__ */ new Set([
-  "the",
-  "a",
-  "an",
-  "to",
-  "of",
-  "in",
-  "and",
-  "or",
-  "for",
-  "is",
-  "on",
-  "at",
-  "with",
-  "be",
-  "as",
-  "it",
-  "that",
-  "this",
-  "its",
-  "must"
-]);
-function tokenize(text) {
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
-}
-function queryTerms(query) {
-  const parts = [];
-  if (query.keyword !== void 0) parts.push(query.keyword);
-  if (query.file !== void 0) parts.push(query.file);
-  if (query.command !== void 0) parts.push(query.command);
-  return tokenize(parts.join(" "));
-}
-function buildCorpus(graph) {
-  const docs = [];
-  const df = /* @__PURE__ */ new Map();
-  let total = 0;
-  let n = 0;
-  for (const lesson of Object.values(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    const toks = tokenize(lesson.rule);
-    n += 1;
-    total += toks.length;
-    docs.push(toks.length);
-    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
+// src/lessons/regex-linear/nfa-compile.ts
+var MAX_NFA_STATES = 2e3;
+var Builder = class {
+  states = [];
+  alloc() {
+    if (this.states.length >= MAX_NFA_STATES) {
+      throw new Error(`NFA state limit exceeded (${MAX_NFA_STATES}); pattern expands too large`);
+    }
+    this.states.push({ eps: [], asserts: [], chars: [] });
+    return this.states.length - 1;
   }
-  const N = Math.max(n, 1);
-  const idf = /* @__PURE__ */ new Map();
-  for (const [t, f] of df) idf.set(t, Math.log(1 + (N - f + 0.5) / (f + 0.5)));
-  return { idf, avgdl: total / N || 1 };
+};
+function isNonLineTerminator(c) {
+  return c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
 }
-function bm25(terms, ruleText, corpus) {
-  const toks = tokenize(ruleText);
-  const dl = toks.length || 1;
-  const tf = /* @__PURE__ */ new Map();
-  for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
-  let score = 0;
-  for (const t of new Set(terms)) {
-    const f = tf.get(t) ?? 0;
-    if (f === 0) continue;
-    const idf = corpus.idf.get(t);
-    score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * dl / corpus.avgdl));
+function compileNode(b, node) {
+  switch (node.k) {
+    case "empty":
+    case "assert": {
+      const s = b.alloc();
+      const e = b.alloc();
+      if (node.k === "assert") b.states[s].asserts.push({ kind: node.kind, target: e });
+      else b.states[s].eps.push(e);
+      return { start: s, end: e };
+    }
+    case "char":
+    case "any":
+    case "class": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const test = node.k === "char" ? (c) => c === node.ch : node.k === "any" ? isNonLineTerminator : node.test;
+      b.states[s].chars.push({ test, target: e });
+      return { start: s, end: e };
+    }
+    case "concat": {
+      if (node.items.length === 0) return compileNode(b, { k: "empty" });
+      let first = null;
+      let prevEnd = -1;
+      for (const item of node.items) {
+        const frag = compileNode(b, item);
+        if (first === null) first = frag;
+        else b.states[prevEnd].eps.push(frag.start);
+        prevEnd = frag.end;
+      }
+      return { start: first.start, end: prevEnd };
+    }
+    case "alt": {
+      const s = b.alloc();
+      const e = b.alloc();
+      for (const opt of node.opts) {
+        const frag = compileNode(b, opt);
+        b.states[s].eps.push(frag.start);
+        b.states[frag.end].eps.push(e);
+      }
+      return { start: s, end: e };
+    }
+    case "opt": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[s].eps.push(frag.start, e);
+      b.states[frag.end].eps.push(e);
+      return { start: s, end: e };
+    }
+    case "star": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[s].eps.push(frag.start, e);
+      b.states[frag.end].eps.push(frag.start, e);
+      return { start: s, end: e };
+    }
+    case "plus": {
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[frag.end].eps.push(frag.start, e);
+      return { start: frag.start, end: e };
+    }
   }
-  return score;
+}
+function compileNfa(ast) {
+  const b = new Builder();
+  const { start, end } = compileNode(b, ast);
+  return { states: b.states, start, accept: end };
 }
 
-// src/lessons/keyword-signal.ts
-var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
-function isLowSignalKeyword(pattern) {
-  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
+// src/lessons/regex-linear/nfa.ts
+function wordBoundary(input, pos) {
+  const before = pos > 0 && /[A-Za-z0-9_]/.test(input[pos - 1]);
+  const after = pos < input.length && /[A-Za-z0-9_]/.test(input[pos]);
+  return before !== after;
 }
-function splitRawTokens(pattern) {
-  return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+function assertHolds(kind, input, pos) {
+  switch (kind) {
+    case "start":
+      return pos === 0;
+    case "end":
+      return pos === input.length;
+    case "wordB":
+      return wordBoundary(input, pos);
+    case "nonWordB":
+      return !wordBoundary(input, pos);
+  }
 }
-function keywordNeedleLosesTokens(pattern) {
-  const raw = splitRawTokens(pattern);
-  if (raw.length < 2) return false;
-  return tokenize(pattern).length !== raw.length;
+function buildMatcher(ast) {
+  const { states, start, accept } = compileNfa(ast);
+  const closure = (set, idx, input, pos, budget) => {
+    const stack = [idx];
+    while (stack.length > 0) {
+      if (budget.remaining <= 0) return;
+      const cur = stack.pop();
+      if (set.has(cur)) continue;
+      set.add(cur);
+      budget.remaining -= 1;
+      for (const t of states[cur].eps) if (!set.has(t)) stack.push(t);
+      for (const a of states[cur].asserts) {
+        if (assertHolds(a.kind, input, pos) && !set.has(a.target)) stack.push(a.target);
+      }
+    }
+  };
+  return {
+    // The input is matched in full (no truncation — truncation would miss suffix
+    // matches and let `$` falsely match an invented endpoint). Work is bounded by
+    // the shared budget instead: when it runs out we report a safe non-match.
+    test(input, budget) {
+      const b = budget ?? { remaining: Number.POSITIVE_INFINITY };
+      if (b.remaining <= 0) return false;
+      let current = /* @__PURE__ */ new Set();
+      for (let pos = 0; pos <= input.length; pos += 1) {
+        closure(current, start, input, pos, b);
+        if (current.has(accept)) return true;
+        if (b.remaining <= 0) return false;
+        if (pos === input.length) break;
+        const ch = input[pos];
+        const next = /* @__PURE__ */ new Set();
+        for (const s of current) {
+          b.remaining -= 1;
+          for (const t of states[s].chars) {
+            if (t.test(ch)) closure(next, t.target, input, pos + 1, b);
+          }
+        }
+        current = next;
+      }
+      return current.has(accept);
+    }
+  };
 }
-function activeTriggerIds(graph) {
-  const ids = /* @__PURE__ */ new Set();
-  for (const lesson of Object.values(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    for (const t of lesson.triggers) ids.add(t);
+
+// src/lessons/regex-linear/ast.ts
+var UnsupportedRegexError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedRegexError";
   }
-  return ids;
-}
-function deadFileGlobIds(graph, knownPaths) {
-  const active = activeTriggerIds(graph);
-  const paths = [...knownPaths];
-  const dead = /* @__PURE__ */ new Set();
-  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
-    if (trigger.kind !== "file_glob") continue;
-    if (!active.has(triggerId)) continue;
-    const isMatch = picomatch(trigger.pattern, { dot: true });
-    if (!paths.some((p) => isMatch(p))) dead.add(triggerId);
+};
+
+// src/lessons/regex-linear/parse-helpers.ts
+var MAX_REPEAT = 1e3;
+var isWord = (c) => /[A-Za-z0-9_]/.test(c);
+function expandRepeat(atom, min, max) {
+  const items = [];
+  for (let k = 0; k < min; k += 1) items.push(atom);
+  if (max === Infinity) {
+    items.push({ k: "star", node: atom });
+  } else {
+    for (let k = min; k < max; k += 1) items.push({ k: "opt", node: atom });
   }
-  return dead;
+  if (items.length === 0) return { k: "empty" };
+  return items.length === 1 ? items[0] : { k: "concat", items };
 }
-function collectDeadFileGlobs(graph, findings, knownPaths) {
-  for (const triggerId of deadFileGlobIds(graph, knownPaths)) {
-    findings.push({
-      level: "warning",
-      code: "DEAD_FILE_GLOB",
-      message: `file_glob trigger "${triggerId}" (${graph.triggers[triggerId]?.pattern ?? ""}) matches no file in the working tree \u2014 the lesson is unreachable via this trigger (a rename likely moved the path). Re-point it at the current path, or detach it with \`lessons untrigger\`, or run \`lessons prune --apply\`.`,
-      triggerId
-    });
+function escapeClass(c) {
+  switch (c) {
+    case "d":
+      return (x) => x >= "0" && x <= "9";
+    case "D":
+      return (x) => !(x >= "0" && x <= "9");
+    case "w":
+      return isWord;
+    case "W":
+      return (x) => !isWord(x);
+    case "s":
+      return (x) => /\s/.test(x);
+    case "S":
+      return (x) => !/\s/.test(x);
+    default:
+      return null;
   }
 }
-function fileGlobMatchCount(pattern, knownPaths) {
-  const isMatch = picomatch(pattern, { dot: true });
-  let n = 0;
-  for (const p of knownPaths) if (isMatch(p)) n += 1;
-  return n;
+var HEX2 = /^[0-9a-fA-F]{2}$/;
+var HEX4 = /^[0-9a-fA-F]{4}$/;
+function readUnicodeEscape(src, i, c) {
+  if (c === "x") {
+    const hex2 = src.slice(i, i + 2);
+    return HEX2.test(hex2) ? { ch: String.fromCharCode(parseInt(hex2, 16)), len: 2 } : { ch: "x", len: 0 };
+  }
+  const hex = src.slice(i, i + 4);
+  return HEX4.test(hex) ? { ch: String.fromCharCode(parseInt(hex, 16)), len: 4 } : { ch: "u", len: 0 };
 }
-var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
-function collectRunnerAnchoredPatterns(graph, findings) {
-  const active = activeTriggerIds(graph);
-  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
-    if (trigger.kind !== "command_pattern") continue;
-    if (!active.has(triggerId)) continue;
-    if (!RUNNER_ANCHOR.test(trigger.pattern)) continue;
-    findings.push({
-      level: "warning",
-      code: "RUNNER_ANCHORED_PATTERN",
-      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) is anchored to one runner \u2014 it won't fire for the same task via another runner (e.g. \`npx\` vs \`pnpm\`). Drop the \`^<runner>\` anchor and key on the task (e.g. \`\\bvitest\\b\`).`,
-      triggerId
-    });
+function readControlEscape(src, i) {
+  const x = src[i];
+  if (x === void 0 || !/[A-Za-z]/.test(x)) {
+    throw new UnsupportedRegexError("\\c must be followed by a letter");
   }
+  return { ch: String.fromCharCode(x.charCodeAt(0) & 31), len: 1 };
 }
-
-// src/lessons/capture-guardrails.ts
-var WIDE_GLOB_MATCH_COUNT = 40;
-var MAX_RECOMMENDED_TRIGGERS = 8;
-function isBroadGlob(pattern) {
-  const p = pattern.trim();
-  if (p === "*" || p === "**") return true;
-  if (!p.includes("**")) return false;
-  const basename5 = p.slice(p.lastIndexOf("/") + 1);
-  return basename5.startsWith("*");
+function classEscapeChar(src, i, e) {
+  if (e === "b") return { ch: "\b", len: 0 };
+  if (e === "c") return readControlEscape(src, i);
+  if (e === "x" || e === "u") return readUnicodeEscape(src, i, e);
+  return { ch: escapeLiteral(e), len: 0 };
 }
-function inspectCapturedLesson(graph, lessonId, knownPaths) {
-  const lesson = graph.lessons[lessonId];
-  if (lesson === void 0) return [];
-  const warnings = [];
-  if (lesson.triggers.length > MAX_RECOMMENDED_TRIGGERS) {
-    warnings.push({
-      code: "OVERSIZED_LESSON_TRIGGERS",
-      message: `Lesson "${lessonId}" has ${lesson.triggers.length} triggers (recommended \u2264 ${MAX_RECOMMENDED_TRIGGERS}); broad trigger sets fire on too many edits and dilute recall \u2014 prefer a few specific triggers.`
-    });
+function escapeLiteral(c) {
+  switch (c) {
+    case "t":
+      return "	";
+    case "n":
+      return "\n";
+    case "r":
+      return "\r";
+    case "f":
+      return "\f";
+    case "v":
+      return "\v";
+    case "0":
+      return "\0";
+    default:
+      return c;
   }
-  const triggers = lesson.triggers.map((id) => graph.triggers[id]).filter((t) => t !== void 0);
-  const broad = triggers.filter((t) => t.kind === "file_glob" && isBroadGlob(t.pattern)).map((t) => t.pattern);
-  if (broad.length > 0) {
-    warnings.push({
-      code: "BROAD_GLOB_TRIGGER",
-      message: `Lesson "${lessonId}" has broad file glob(s) (${broad.join(", ")}) that match large swaths of the tree; prefer a path specific to the lesson.`
-    });
+}
+
+// src/lessons/regex-linear/parse.ts
+function parseRegex(src) {
+  let i = 0;
+  const peek = () => src[i];
+  const eat = () => src[i++];
+  function parseAlt() {
+    const opts = [parseConcat()];
+    while (peek() === "|") {
+      i += 1;
+      opts.push(parseConcat());
+    }
+    return opts.length === 1 ? opts[0] : { k: "alt", opts };
   }
-  if (triggers.length > 0 && triggers.every((t) => t.kind === "keyword")) {
-    warnings.push({
-      code: "KEYWORD_ONLY_LESSON",
-      message: `Lesson "${lessonId}" has only keyword triggers; mandatory --file/--cmd recall surfaces these only when the keyword appears as a path/command token, so it fires less reliably \u2014 add a file_glob or command_pattern trigger for precise recall.`
-    });
+  function parseConcat() {
+    const items = [];
+    while (i < src.length && peek() !== "|" && peek() !== ")") {
+      items.push(parseQuantified());
+    }
+    if (items.length === 0) return { k: "empty" };
+    return items.length === 1 ? items[0] : { k: "concat", items };
   }
-  const lowSignal = triggers.filter((t) => t.kind === "keyword" && isLowSignalKeyword(t.pattern)).map((t) => t.pattern);
-  if (lowSignal.length > 0) {
-    warnings.push({
-      code: "LOW_SIGNAL_KEYWORD",
-      message: `Lesson "${lessonId}" has long keyword trigger(s) (${lowSignal.join(", ")}); recall matches a keyword only as a substring of --keyword or a contiguous token-run in the file/command, so a pattern past ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens rarely fires \u2014 use a short distinctive phrase.`
-    });
+  function parseQuantified() {
+    const atom = parseAtom();
+    const q = peek();
+    if (q === "*" || q === "+" || q === "?") {
+      i += 1;
+      if (peek() === "?") i += 1;
+      return q === "*" ? { k: "star", node: atom } : q === "+" ? { k: "plus", node: atom } : { k: "opt", node: atom };
+    }
+    if (q === "{") {
+      const repeat = tryParseBrace();
+      if (repeat !== null) return expandRepeat(atom, repeat.min, repeat.max);
+    }
+    return atom;
   }
-  const stopworded = triggers.filter((t) => t.kind === "keyword" && keywordNeedleLosesTokens(t.pattern)).map((t) => t.pattern);
-  if (stopworded.length > 0) {
-    warnings.push({
-      code: "STOPWORD_KEYWORD",
-      message: `Lesson "${lessonId}" has keyword trigger(s) containing stopwords/short words (${stopworded.join(", ")}); recall filters them from the pattern but NOT from the file/command text, so the phrase can never match contiguously on the --file/--cmd path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art").`
-    });
+  function tryParseBrace() {
+    const m = /^\{(\d+)(,(\d*)?)?\}/.exec(src.slice(i));
+    if (m === null) return null;
+    i += m[0].length;
+    if (peek() === "?") i += 1;
+    const min = Number(m[1]);
+    const max = m[2] === void 0 ? min : m[3] === "" || m[3] === void 0 ? Infinity : Number(m[3]);
+    if (min > MAX_REPEAT || max !== Infinity && max > MAX_REPEAT) {
+      throw new UnsupportedRegexError(`Repeat count over ${MAX_REPEAT} not supported: {${m[1]}\u2026}`);
+    }
+    return { min, max };
   }
-  if (knownPaths !== void 0) {
-    const dead = deadFileGlobIds(graph, knownPaths);
-    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
-    if (deadHere.length > 0) {
-      warnings.push({
-        code: "DEAD_GLOB",
-        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
-      });
+  function parseAtom() {
+    const c = peek();
+    if (c === "(") return parseGroup();
+    if (c === "[") return parseClass();
+    if (c === "\\") return parseEscape();
+    if (c === ".") {
+      i += 1;
+      return { k: "any" };
     }
-    const wide = triggers.filter((t) => t.kind === "file_glob" && !isBroadGlob(t.pattern)).filter((t) => fileGlobMatchCount(t.pattern, knownPaths) > WIDE_GLOB_MATCH_COUNT).map((t) => t.pattern);
-    if (wide.length > 0) {
-      warnings.push({
-        code: "WIDE_GLOB_MATCH",
-        message: `Lesson "${lessonId}" has file glob(s) (${wide.join(", ")}) matching more than ${WIDE_GLOB_MATCH_COUNT} files in the working tree; narrow to the file-CLASS where the rule actually applies so it does not fire on unrelated edits.`
-      });
+    if (c === "^") {
+      i += 1;
+      return { k: "assert", kind: "start" };
     }
-  }
-  return warnings;
-}
-
-// src/lessons/capture-near-duplicate.ts
-var NEAR_DUPLICATE_THRESHOLD = 0.6;
-function nearDuplicateWarning(graph, lessonId) {
-  const subject = graph.lessons[lessonId];
-  if (subject === void 0) return null;
-  const subjectTokens = new Set(tokenize(subject.rule));
-  if (subjectTokens.size === 0) return null;
-  let best = null;
-  for (const [id, other] of Object.entries(graph.lessons)) {
-    if (id === lessonId || other.status !== "active") continue;
-    const otherTokens = new Set(tokenize(other.rule));
-    if (otherTokens.size === 0) continue;
-    const score = jaccard(subjectTokens, otherTokens);
-    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
-      best = { id, score };
+    if (c === "$") {
+      i += 1;
+      return { k: "assert", kind: "end" };
+    }
+    if (c === void 0 || c === "*" || c === "+" || c === "?" || c === ")") {
+      throw new UnsupportedRegexError(`Unexpected '${c ?? "<end>"}' in pattern`);
     }
+    i += 1;
+    return { k: "char", ch: c };
   }
-  if (best === null) return null;
-  return {
-    code: "NEAR_DUPLICATE_LESSON",
-    message: `Lesson "${lessonId}" closely resembles active lesson "${best.id}" (~${Math.round(best.score * 100)}% token overlap); consider updating "${best.id}" instead of adding a paraphrase (recall would surface both).`
-  };
-}
-function jaccard(a, b) {
-  let intersection = 0;
-  for (const t of a) if (b.has(t)) intersection += 1;
-  return intersection / (a.size + b.size - intersection);
-}
-
-// src/core/errors.ts
-var AgentsMeshError = class extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options);
-    this.name = "AgentsMeshError";
-    this.code = code;
+  function parseGroup() {
+    i += 1;
+    if (peek() === "?") {
+      const c2 = src[i + 1];
+      if (c2 === "=" || c2 === "!" || c2 === "<") {
+        if (!(c2 === "<" && /[A-Za-z]/.test(src[i + 2] ?? ""))) {
+          throw new UnsupportedRegexError("Lookaround assertions are not supported");
+        }
+      }
+      if (c2 === ":") i += 2;
+      else if (c2 === "<") {
+        i += 2;
+        while (i < src.length && src[i] !== ">") i += 1;
+        i += 1;
+      }
+    }
+    const inner = parseAlt();
+    if (peek() !== ")") throw new UnsupportedRegexError("Unbalanced group");
+    i += 1;
+    return inner;
   }
-};
-var LockAcquisitionError = class extends AgentsMeshError {
-  lockPath;
-  holder;
-  /** Human-readable lock name surfaced in the message, e.g. "lessons lock". */
-  label;
-  constructor(lockPath, holder, options) {
-    const label = options?.label ?? "lock";
-    super(
-      "AM_LOCK_ACQUISITION_FAILED",
-      `Could not acquire ${label} at ${lockPath}: currently held by ${holder}. Wait for the other process to finish, or remove ${lockPath} manually if you are sure no agentsmesh process is running.`,
-      options
-    );
-    this.name = "LockAcquisitionError";
-    this.lockPath = lockPath;
-    this.holder = holder;
-    this.label = label;
-  }
-};
-var FileSystemError = class extends AgentsMeshError {
-  path;
-  errnoCode;
-  constructor(path, message, options) {
-    super("AM_FILESYSTEM", message, options);
-    this.name = "FileSystemError";
-    this.path = path;
-    this.errnoCode = options?.errnoCode;
-  }
-};
-
-// src/utils/filesystem/process-lock.ts
-var DEFAULT_STALE_MS = 6e4;
-var DEFAULT_RETRIES = 30;
-var DEFAULT_RETRY_DELAY_MS = 200;
-var YOUNG_LOCK_GRACE_MS = 2e3;
-async function acquireProcessLock(lockPath, opts = {}) {
-  const retries = opts.retries ?? DEFAULT_RETRIES;
-  const delay = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
-  const stale = opts.staleMs ?? DEFAULT_STALE_MS;
-  await mkdir(dirname(lockPath), { recursive: true });
-  let attempt = 0;
-  while (true) {
-    const acquired = await tryAcquire(lockPath);
-    if (acquired) return acquired;
-    const existing = await inspectLock(lockPath);
-    if (existing !== "young" && isStale(existing, stale)) {
-      await rm(lockPath, { recursive: true, force: true }).catch(() => {
-      });
-      continue;
-    }
-    if (attempt >= retries) {
-      const holder = existing === "young" ? null : existing;
-      throw new LockAcquisitionError(lockPath, describeHolder(holder), { label: opts.label });
+  function parseEscape() {
+    i += 1;
+    const c = peek();
+    if (c === void 0) throw new UnsupportedRegexError("Trailing backslash");
+    if (/[1-9]/.test(c) || c === "k")
+      throw new UnsupportedRegexError("Backreferences are not supported");
+    i += 1;
+    if (c === "b") return { k: "assert", kind: "wordB" };
+    if (c === "B") return { k: "assert", kind: "nonWordB" };
+    const cls = escapeClass(c);
+    if (cls !== null) return { k: "class", test: cls };
+    if (c === "x" || c === "u" || c === "c") {
+      const { ch, len } = c === "c" ? readControlEscape(src, i) : readUnicodeEscape(src, i, c);
+      i += len;
+      return { k: "char", ch };
     }
-    attempt++;
-    await sleep(delay);
+    return { k: "char", ch: escapeLiteral(c) };
   }
-}
-async function tryAcquire(lockPath) {
-  try {
-    await mkdir(lockPath, { recursive: false });
-  } catch (err) {
-    if (err.code === "EEXIST") return null;
-    throw err;
+  function parseClass() {
+    i += 1;
+    const negate = peek() === "^";
+    if (negate) i += 1;
+    const tests = [];
+    while (i < src.length && peek() !== "]") {
+      tests.push(parseClassMember());
+    }
+    if (peek() !== "]") throw new UnsupportedRegexError("Unterminated character class");
+    i += 1;
+    const base = (c) => tests.some((t) => t(c));
+    return { k: "class", test: negate ? (c) => !base(c) : base };
   }
-  const metadataPath = join(lockPath, "holder.json");
-  const metadata = {
-    pid: process.pid,
-    started: Date.now(),
-    hostname: getHostname()
-  };
-  await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
-  let released = false;
-  const cleanup = () => {
-    if (released) return;
-    released = true;
-    try {
-      rmSync(lockPath, { recursive: true, force: true });
-    } catch {
+  function parseClassMember() {
+    let lo;
+    if (peek() === "\\") {
+      i += 1;
+      const e = eat();
+      const cls = escapeClass(e);
+      if (cls !== null) return cls;
+      const r = classEscapeChar(src, i, e);
+      i += r.len;
+      lo = r.ch;
+    } else {
+      lo = eat();
     }
-  };
-  const signalHandler = (signal) => {
-    cleanup();
-    process.kill(process.pid, signal);
-  };
-  process.once("SIGINT", signalHandler);
-  process.once("SIGTERM", signalHandler);
-  process.once("exit", cleanup);
-  return async () => {
-    if (released) return;
-    released = true;
-    process.off("SIGINT", signalHandler);
-    process.off("SIGTERM", signalHandler);
-    process.off("exit", cleanup);
-    await rm(lockPath, { recursive: true, force: true }).catch(() => {
-    });
-  };
-}
-async function inspectLock(lockPath) {
-  try {
-    const raw = await readFile(join(lockPath, "holder.json"), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (!isLockMetadata(parsed)) return null;
-    return parsed;
-  } catch {
-    try {
-      const info = await stat(lockPath);
-      const ageMs = Date.now() - info.mtimeMs;
-      if (ageMs < YOUNG_LOCK_GRACE_MS) return "young";
-    } catch {
+    if (peek() === "-" && src[i + 1] !== void 0 && src[i + 1] !== "]") {
+      i += 1;
+      let hi;
+      if (peek() === "\\") {
+        i += 1;
+        const e2 = eat();
+        const r = classEscapeChar(src, i, e2);
+        i += r.len;
+        hi = r.ch;
+      } else {
+        hi = eat();
+      }
+      const a = lo.codePointAt(0);
+      const b = hi.codePointAt(0);
+      return (c) => {
+        const p = c.codePointAt(0);
+        return p >= a && p <= b;
+      };
     }
-    return null;
+    return (c) => c === lo;
   }
+  const ast = parseAlt();
+  if (i !== src.length) throw new UnsupportedRegexError(`Unexpected '${peek()}' at ${i}`);
+  return ast;
 }
-function isStale(meta, staleMs) {
-  if (!meta) return true;
-  const age = Date.now() - meta.started;
-  if (age > staleMs) return true;
-  if (meta.hostname && meta.hostname !== getHostname()) return false;
-  return !isProcessAlive(meta.pid);
-}
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
+
+// src/lessons/regex-linear/index.ts
+var cache = /* @__PURE__ */ new Map();
+function compileLinearMatcher(pattern) {
+  const hit = cache.get(pattern);
+  if (hit !== void 0 || cache.has(pattern)) return hit ?? null;
+  let matcher;
   try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
+    matcher = buildMatcher(parseRegex(pattern));
+  } catch {
+    matcher = null;
   }
-}
-function describeHolder(meta) {
-  if (!meta) return "unknown (unreadable lock metadata)";
-  const host = meta.hostname ? `${meta.hostname}:` : "";
-  return `${host}pid ${meta.pid} (running ${Date.now() - meta.started}ms)`;
-}
-function isLockMetadata(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  return typeof v.pid === "number" && typeof v.started === "number";
-}
-function getHostname() {
-  return hostname();
-}
-function sleep(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  cache.set(pattern, matcher);
+  return matcher;
 }
 
-// src/lessons/lessons-lock.ts
-var LESSONS_LOCK_FILENAME = ".lessons.lock";
-function lessonsLockPath(projectRoot) {
-  return resolve(projectRoot, ".agentsmesh/lessons", LESSONS_LOCK_FILENAME);
+// src/lessons/regex-safety.ts
+var MAX_PATTERN_LENGTH = 1e3;
+function isSafeRegexPattern(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) return false;
+  return compileLinearMatcher(pattern) !== null;
 }
-async function acquireLessonsLock(projectRoot, opts = {}) {
-  const lockPath = lessonsLockPath(projectRoot);
-  await mkdir(dirname(lockPath), { recursive: true });
-  return acquireProcessLock(lockPath, { ...opts, label: "lessons lock" });
+function getCommandMatcher(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) return null;
+  return compileLinearMatcher(pattern);
 }
 
-// src/lessons/validate-checks.ts
-function collectDanglingRefs(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    for (const topicId of lesson.topics) {
-      if (graph.topics[topicId] === void 0) {
-        findings.push({
-          level: "error",
-          code: "DANGLING_TOPIC",
-          message: `Lesson "${lessonId}" references unknown topic "${topicId}".`,
-          lessonId,
-          topicId
-        });
-      }
-    }
-    for (const triggerId of lesson.triggers) {
-      if (graph.triggers[triggerId] === void 0) {
-        findings.push({
-          level: "error",
-          code: "DANGLING_TRIGGER",
-          message: `Lesson "${lessonId}" references unknown trigger "${triggerId}".`,
-          lessonId,
-          triggerId
-        });
-      }
-    }
-    if (lesson.supersededBy !== void 0 && graph.lessons[lesson.supersededBy] === void 0) {
-      findings.push({
-        level: "error",
-        code: "DANGLING_SUPERSEDER",
-        message: `Lesson "${lessonId}" supersededBy unknown lesson "${lesson.supersededBy}".`,
-        lessonId
-      });
-    }
+// src/lessons/command-pattern-breadth.ts
+var COMMAND_PROBE_CORPUS = [
+  "git status",
+  'git commit -m "wip"',
+  "pnpm test",
+  "npx vitest run src/x.test.ts",
+  "ls -la",
+  "cat README.md",
+  "rm -rf dist",
+  "mkdir -p build/out",
+  "node scripts/build.js",
+  "docker compose up -d",
+  "curl -s https://example.com",
+  "echo hello > out.txt",
+  "sed -i 's/a/b/' file.txt",
+  "pnpm lint --fix",
+  "python3 -m pytest",
+  "cargo build --release",
+  "make",
+  "npm install --global typescript",
+  "cp a.txt b.txt",
+  "grep -rn TODO src"
+];
+var BROAD_HIT_RATIO = 0.5;
+var PROBE_BUDGET = 1e5;
+function isBroadCommandPattern(pattern) {
+  const matcher = getCommandMatcher(pattern);
+  if (matcher === null) return false;
+  if (matcher.test("", { remaining: PROBE_BUDGET })) return true;
+  let hits = 0;
+  for (const command of COMMAND_PROBE_CORPUS) {
+    if (matcher.test(command, { remaining: PROBE_BUDGET })) hits += 1;
   }
+  return hits > COMMAND_PROBE_CORPUS.length * BROAD_HIT_RATIO;
 }
-function collectDuplicateRefs(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    for (const topicId of firstDuplicates(lesson.topics)) {
-      findings.push({
-        level: "error",
-        code: "DUPLICATE_TOPIC_REF",
-        message: `Lesson "${lessonId}" references topic "${topicId}" more than once.`,
-        lessonId,
-        topicId
-      });
-    }
-    for (const triggerId of firstDuplicates(lesson.triggers)) {
-      findings.push({
-        level: "error",
-        code: "DUPLICATE_TRIGGER_REF",
-        message: `Lesson "${lessonId}" references trigger "${triggerId}" more than once.`,
-        lessonId,
-        triggerId
-      });
-    }
+
+// src/lessons/ranking-text.ts
+var K1 = 1.5;
+var B = 0.75;
+var STOP = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "to",
+  "of",
+  "in",
+  "and",
+  "or",
+  "for",
+  "is",
+  "on",
+  "at",
+  "with",
+  "be",
+  "as",
+  "it",
+  "that",
+  "this",
+  "its",
+  "must"
+]);
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
+}
+function queryTerms(query) {
+  const parts = [];
+  if (query.keyword !== void 0) parts.push(query.keyword);
+  if (query.file !== void 0) parts.push(query.file);
+  if (query.command !== void 0) parts.push(query.command);
+  return tokenize(parts.join(" "));
+}
+function buildCorpus(graph) {
+  const docs = [];
+  const df = /* @__PURE__ */ new Map();
+  let total = 0;
+  let n = 0;
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    const toks = tokenize(lesson.rule);
+    n += 1;
+    total += toks.length;
+    docs.push(toks.length);
+    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
   }
+  const N = Math.max(n, 1);
+  const idf = /* @__PURE__ */ new Map();
+  for (const [t, f] of df) idf.set(t, Math.log(1 + (N - f + 0.5) / (f + 0.5)));
+  return { idf, avgdl: total / N || 1 };
 }
-function firstDuplicates(ids) {
-  const seen = /* @__PURE__ */ new Set();
-  const dup = /* @__PURE__ */ new Set();
-  for (const id of ids) {
-    if (seen.has(id)) dup.add(id);
-    else seen.add(id);
+function bm25(terms, ruleText, corpus) {
+  const toks = tokenize(ruleText);
+  const dl = toks.length || 1;
+  const tf = /* @__PURE__ */ new Map();
+  for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
+  let score = 0;
+  for (const t of new Set(terms)) {
+    const f = tf.get(t) ?? 0;
+    if (f === 0) continue;
+    const idf = corpus.idf.get(t);
+    score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * dl / corpus.avgdl));
   }
-  return [...dup];
+  return score;
 }
-function collectStatusInvariants(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status === "superseded" && lesson.supersededBy === void 0) {
-      findings.push({
-        level: "error",
-        code: "SUPERSEDED_WITHOUT_TARGET",
-        message: `Lesson "${lessonId}" has status "superseded" but no supersededBy target.`,
-        lessonId
-      });
-    }
-    if (lesson.status === "active" && lesson.supersededBy !== void 0) {
-      findings.push({
-        level: "error",
-        code: "ACTIVE_WITH_SUPERSEDER",
-        message: `Lesson "${lessonId}" has status "active" but declares supersededBy.`,
-        lessonId
-      });
-    }
+
+// src/lessons/keyword-signal.ts
+var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
+function isLowSignalKeyword(pattern) {
+  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
+}
+function splitRawTokens(pattern) {
+  return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function keywordNeedleLosesTokens(pattern) {
+  const raw = splitRawTokens(pattern);
+  if (raw.length < 2) return false;
+  return tokenize(pattern).length !== raw.length;
+}
+
+// src/lessons/trigger-effectiveness.ts
+function ineffectiveTriggers(graph, triggerIds) {
+  const out = [];
+  for (const id of triggerIds) {
+    const trigger = graph.triggers[id];
+    if (trigger === void 0) continue;
+    const reason = ineffectiveReason(trigger.kind, trigger.pattern);
+    if (reason !== null) out.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
   }
+  return out;
 }
-function collectLifecycleInvariants(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.supersededBy === void 0) continue;
-    if (lesson.supersededBy === lessonId) {
-      findings.push({
-        level: "error",
-        code: "SELF_SUPERSEDED",
-        message: `Lesson "${lessonId}" is superseded by itself.`,
-        lessonId
-      });
-      continue;
+function ineffectiveReason(kind, pattern) {
+  if (kind === "keyword") {
+    if (tokenize(pattern).length === 0) {
+      return "keyword has no matchable token after stopword filtering \u2014 it cannot fire on the mandatory --file/--cmd recall path";
     }
-    const target = graph.lessons[lesson.supersededBy];
-    if (target !== void 0 && target.status !== "active") {
-      findings.push({
-        level: "error",
-        code: "INACTIVE_SUPERSEDER",
-        message: `Lesson "${lessonId}" is superseded by "${lesson.supersededBy}", which is itself ${target.status} \u2014 the chain dead-ends with no live replacement.`,
-        lessonId
-      });
+    if (keywordNeedleLosesTokens(pattern)) {
+      return "keyword contains stopwords/short words, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path";
     }
+    return null;
   }
-  collectSupersedeCycles(graph, findings);
-}
-function collectSupersedeCycles(graph, findings) {
-  const reported = /* @__PURE__ */ new Set();
-  for (const startId of Object.keys(graph.lessons)) {
-    const seen = /* @__PURE__ */ new Set();
-    let cur = startId;
-    while (cur !== void 0) {
-      if (seen.has(cur)) {
-        if (cur !== startId || reported.has(cur)) break;
-        reported.add(cur);
-        findings.push({
-          level: "error",
-          code: "SUPERSEDE_CYCLE",
-          message: `Lesson "${startId}" is part of a supersededBy cycle.`,
-          lessonId: startId
-        });
-        break;
-      }
-      seen.add(cur);
-      const next = graph.lessons[cur]?.supersededBy;
-      if (next === cur) break;
-      cur = next;
+  if (kind === "command_pattern") {
+    let valid = true;
+    try {
+      new RegExp(pattern);
+    } catch {
+      valid = false;
     }
-  }
-}
-function collectReachability(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status === "active" && lesson.triggers.length === 0) {
-      findings.push({
-        level: "warning",
-        code: "UNREACHABLE_LESSON",
-        message: `Active lesson "${lessonId}" has no triggers and can never be recalled.`,
-        lessonId
-      });
+    if (!valid) {
+      return "invalid regex \u2014 recall compiles it with new RegExp and swallows the throw as a non-match, so it never fires";
+    }
+    if (!isSafeRegexPattern(pattern)) {
+      return "regex is outside the provably-linear engine \u2014 recall skips it (ReDoS guard), so it never fires";
     }
+    return null;
   }
+  return null;
 }
-function collectOrphans(graph, findings) {
-  const referencedTopics = /* @__PURE__ */ new Set();
-  const referencedTriggers = /* @__PURE__ */ new Set();
-  for (const lesson of Object.values(graph.lessons)) {
-    for (const t of lesson.topics) referencedTopics.add(t);
-    for (const t of lesson.triggers) referencedTriggers.add(t);
+function blockingDeadTriggers(graph, triggerIds) {
+  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
+}
+
+// src/lessons/add-gates.ts
+function assertRuleShape(rule) {
+  const trimmed = rule.trim();
+  if (trimmed.length === 0) throw new EmptyRuleError();
+  if (trimmed.length > MAX_RULE_LENGTH) throw new RuleTooLongError(trimmed.length, MAX_RULE_LENGTH);
+  return trimmed;
+}
+function skipsTriggerGates(input, options) {
+  return options.allowNoTrigger === true || input.scope === "always";
+}
+function countInputTriggers(triggers) {
+  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
+}
+function assertTriggerInputs(input, options, existingTriggerCount) {
+  if (!skipsTriggerGates(input, options) && countInputTriggers(input.triggers) === 0 && existingTriggerCount === 0) {
+    throw new NoTriggerError();
   }
-  for (const topicId of Object.keys(graph.topics)) {
-    if (!referencedTopics.has(topicId)) {
-      findings.push({
-        level: "warning",
-        code: "ORPHAN_TOPIC",
-        message: `Topic "${topicId}" is not referenced by any lesson.`,
-        topicId
-      });
-    }
+  if (options.allowNoTrigger !== true) {
+    const broad = (input.triggers.commands ?? []).find(isBroadCommandPattern);
+    if (broad !== void 0) throw new BroadCommandPatternError(broad);
   }
-  for (const triggerId of Object.keys(graph.triggers)) {
-    if (!referencedTriggers.has(triggerId)) {
-      findings.push({
-        level: "warning",
-        code: "ORPHAN_TRIGGER",
-        message: `Trigger "${triggerId}" is not referenced by any lesson.`,
-        triggerId
-      });
-    }
+}
+function assertRecallable(graph, resultingTriggers) {
+  const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
+  if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
+    throw new UnrecallableLessonError(blockingDead);
   }
 }
 
-// src/lessons/regex-linear/nfa-compile.ts
-var MAX_NFA_STATES = 2e3;
-var Builder = class {
-  states = [];
-  alloc() {
-    if (this.states.length >= MAX_NFA_STATES) {
-      throw new Error(`NFA state limit exceeded (${MAX_NFA_STATES}); pattern expands too large`);
-    }
-    this.states.push({ eps: [], asserts: [], chars: [] });
-    return this.states.length - 1;
+// src/lessons/glob-breadth.ts
+var WILDCARD = /[*?[\]]/;
+function globNarrowness(pattern) {
+  const segments = pattern.replaceAll("\\", "/").split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (segments.length === 0) return 0;
+  let literal = 0;
+  let globstars = 0;
+  for (const segment of segments) {
+    if (segment === "**") globstars += 1;
+    else if (!WILDCARD.test(segment)) literal += 1;
   }
-};
-function isNonLineTerminator(c) {
-  return c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
+  return literal / (segments.length + globstars);
 }
-function compileNode(b, node) {
-  switch (node.k) {
-    case "empty":
-    case "assert": {
-      const s = b.alloc();
-      const e = b.alloc();
-      if (node.k === "assert") b.states[s].asserts.push({ kind: node.kind, target: e });
-      else b.states[s].eps.push(e);
-      return { start: s, end: e };
-    }
-    case "char":
-    case "any":
-    case "class": {
-      const s = b.alloc();
-      const e = b.alloc();
-      const test = node.k === "char" ? (c) => c === node.ch : node.k === "any" ? isNonLineTerminator : node.test;
-      b.states[s].chars.push({ test, target: e });
-      return { start: s, end: e };
-    }
-    case "concat": {
-      if (node.items.length === 0) return compileNode(b, { k: "empty" });
-      let first = null;
-      let prevEnd = -1;
-      for (const item of node.items) {
-        const frag = compileNode(b, item);
-        if (first === null) first = frag;
-        else b.states[prevEnd].eps.push(frag.start);
-        prevEnd = frag.end;
-      }
-      return { start: first.start, end: prevEnd };
-    }
-    case "alt": {
-      const s = b.alloc();
-      const e = b.alloc();
-      for (const opt of node.opts) {
-        const frag = compileNode(b, opt);
-        b.states[s].eps.push(frag.start);
-        b.states[frag.end].eps.push(e);
-      }
-      return { start: s, end: e };
-    }
-    case "opt": {
-      const s = b.alloc();
-      const e = b.alloc();
-      const frag = compileNode(b, node.node);
-      b.states[s].eps.push(frag.start, e);
-      b.states[frag.end].eps.push(e);
-      return { start: s, end: e };
-    }
-    case "star": {
-      const s = b.alloc();
-      const e = b.alloc();
-      const frag = compileNode(b, node.node);
-      b.states[s].eps.push(frag.start, e);
-      b.states[frag.end].eps.push(frag.start, e);
-      return { start: s, end: e };
-    }
-    case "plus": {
-      const e = b.alloc();
-      const frag = compileNode(b, node.node);
-      b.states[frag.end].eps.push(frag.start, e);
-      return { start: frag.start, end: e };
-    }
+var BROAD_GLOB_NARROWNESS = 0.34;
+function isBroadFileGlob(pattern) {
+  return globNarrowness(pattern) < BROAD_GLOB_NARROWNESS;
+}
+function activeTriggerIds(graph) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) ids.add(t);
   }
+  return ids;
 }
-function compileNfa(ast) {
-  const b = new Builder();
-  const { start, end } = compileNode(b, ast);
-  return { states: b.states, start, accept: end };
+function deadFileGlobIds(graph, knownPaths) {
+  const active = activeTriggerIds(graph);
+  const paths = [...knownPaths];
+  const dead = /* @__PURE__ */ new Set();
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!active.has(triggerId)) continue;
+    const isMatch = picomatch(trigger.pattern, { dot: true });
+    if (!paths.some((p) => isMatch(p))) dead.add(triggerId);
+  }
+  return dead;
+}
+function collectDeadFileGlobs(graph, findings, knownPaths) {
+  for (const triggerId of deadFileGlobIds(graph, knownPaths)) {
+    findings.push({
+      level: "warning",
+      code: "DEAD_FILE_GLOB",
+      message: `file_glob trigger "${triggerId}" (${graph.triggers[triggerId]?.pattern ?? ""}) matches no file in the working tree \u2014 the lesson is unreachable via this trigger (a rename likely moved the path). Re-point it at the current path, or detach it with \`lessons untrigger\`, or run \`lessons prune --apply\`.`,
+      triggerId
+    });
+  }
+}
+function fileGlobMatchCount(pattern, knownPaths) {
+  const isMatch = picomatch(pattern, { dot: true });
+  let n = 0;
+  for (const p of knownPaths) if (isMatch(p)) n += 1;
+  return n;
+}
+var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
+function collectRunnerAnchoredPatterns(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    if (!active.has(triggerId)) continue;
+    if (!RUNNER_ANCHOR.test(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "RUNNER_ANCHORED_PATTERN",
+      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) is anchored to one runner \u2014 it won't fire for the same task via another runner (e.g. \`npx\` vs \`pnpm\`). Drop the \`^<runner>\` anchor and key on the task (e.g. \`\\bvitest\\b\`).`,
+      triggerId
+    });
+  }
+}
+function collectBroadFileGlobs(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!active.has(triggerId)) continue;
+    if (!isBroadFileGlob(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "BROAD_FILE_GLOB",
+      message: `file_glob trigger "${triggerId}" (${trigger.pattern}) matches most of the repository, so it outranks nothing and crowds the recall budget. Narrow it to the directory or file class the rule is really about, or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
+function collectBroadCommandPatterns(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    if (!active.has(triggerId)) continue;
+    if (!isBroadCommandPattern(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "BROAD_COMMAND_PATTERN",
+      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) matches nearly every command, so the lesson fires on every recall. Key it on the action (e.g. \`\\bgit commit\\b\`), or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
 }
 
-// src/lessons/regex-linear/nfa.ts
-function wordBoundary(input, pos) {
-  const before = pos > 0 && /[A-Za-z0-9_]/.test(input[pos - 1]);
-  const after = pos < input.length && /[A-Za-z0-9_]/.test(input[pos]);
-  return before !== after;
+// src/lessons/capture-guardrails.ts
+var WIDE_GLOB_MATCH_COUNT = 40;
+var MAX_RECOMMENDED_TRIGGERS = 8;
+function isBroadGlob(pattern) {
+  const p = pattern.trim();
+  if (p === "*" || p === "**") return true;
+  if (!p.includes("**")) return false;
+  const basename5 = p.slice(p.lastIndexOf("/") + 1);
+  return basename5.startsWith("*");
 }
-function assertHolds(kind, input, pos) {
-  switch (kind) {
-    case "start":
-      return pos === 0;
-    case "end":
-      return pos === input.length;
-    case "wordB":
-      return wordBoundary(input, pos);
-    case "nonWordB":
-      return !wordBoundary(input, pos);
+function inspectCapturedLesson(graph, lessonId, knownPaths) {
+  const lesson = graph.lessons[lessonId];
+  if (lesson === void 0) return [];
+  const warnings = [];
+  if (lesson.triggers.length > MAX_RECOMMENDED_TRIGGERS) {
+    warnings.push({
+      code: "OVERSIZED_LESSON_TRIGGERS",
+      message: `Lesson "${lessonId}" has ${lesson.triggers.length} triggers (recommended \u2264 ${MAX_RECOMMENDED_TRIGGERS}); broad trigger sets fire on too many edits and dilute recall \u2014 prefer a few specific triggers.`
+    });
+  }
+  const triggers = lesson.triggers.map((id) => graph.triggers[id]).filter((t) => t !== void 0);
+  const broad = triggers.filter((t) => t.kind === "file_glob" && isBroadGlob(t.pattern)).map((t) => t.pattern);
+  if (broad.length > 0) {
+    warnings.push({
+      code: "BROAD_GLOB_TRIGGER",
+      message: `Lesson "${lessonId}" has broad file glob(s) (${broad.join(", ")}) that match large swaths of the tree; prefer a path specific to the lesson.`
+    });
+  }
+  if (triggers.length > 0 && triggers.every((t) => t.kind === "keyword")) {
+    warnings.push({
+      code: "KEYWORD_ONLY_LESSON",
+      message: `Lesson "${lessonId}" has only keyword triggers; mandatory --file/--cmd recall surfaces these only when the keyword appears as a path/command token, so it fires less reliably \u2014 add a file_glob or command_pattern trigger for precise recall.`
+    });
+  }
+  const lowSignal = triggers.filter((t) => t.kind === "keyword" && isLowSignalKeyword(t.pattern)).map((t) => t.pattern);
+  if (lowSignal.length > 0) {
+    warnings.push({
+      code: "LOW_SIGNAL_KEYWORD",
+      message: `Lesson "${lessonId}" has long keyword trigger(s) (${lowSignal.join(", ")}); recall matches a keyword only as a contiguous token-run in --keyword or the file/command, so a pattern past ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens rarely fires \u2014 use a short distinctive phrase.`
+    });
+  }
+  const stopworded = triggers.filter((t) => t.kind === "keyword" && keywordNeedleLosesTokens(t.pattern)).map((t) => t.pattern);
+  if (stopworded.length > 0) {
+    warnings.push({
+      code: "STOPWORD_KEYWORD",
+      message: `Lesson "${lessonId}" has keyword trigger(s) containing stopwords/short words (${stopworded.join(", ")}); recall filters them from the pattern but NOT from the file/command text, so the phrase can never match contiguously on the --file/--cmd path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art").`
+    });
   }
+  if (knownPaths !== void 0) {
+    const dead = deadFileGlobIds(graph, knownPaths);
+    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
+    if (deadHere.length > 0) {
+      warnings.push({
+        code: "DEAD_GLOB",
+        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
+      });
+    }
+    const wide = triggers.filter((t) => t.kind === "file_glob" && !isBroadGlob(t.pattern)).filter((t) => fileGlobMatchCount(t.pattern, knownPaths) > WIDE_GLOB_MATCH_COUNT).map((t) => t.pattern);
+    if (wide.length > 0) {
+      warnings.push({
+        code: "WIDE_GLOB_MATCH",
+        message: `Lesson "${lessonId}" has file glob(s) (${wide.join(", ")}) matching more than ${WIDE_GLOB_MATCH_COUNT} files in the working tree; narrow to the file-CLASS where the rule actually applies so it does not fire on unrelated edits.`
+      });
+    }
+  }
+  return warnings;
 }
-function buildMatcher(ast) {
-  const { states, start, accept } = compileNfa(ast);
-  const closure = (set, idx, input, pos, budget) => {
-    const stack = [idx];
-    while (stack.length > 0) {
-      if (budget.remaining <= 0) return;
-      const cur = stack.pop();
-      if (set.has(cur)) continue;
-      set.add(cur);
-      budget.remaining -= 1;
-      for (const t of states[cur].eps) if (!set.has(t)) stack.push(t);
-      for (const a of states[cur].asserts) {
-        if (assertHolds(a.kind, input, pos) && !set.has(a.target)) stack.push(a.target);
-      }
+
+// src/lessons/capture-near-duplicate.ts
+var NEAR_DUPLICATE_THRESHOLD = 0.6;
+function nearDuplicateWarning(graph, lessonId) {
+  const subject = graph.lessons[lessonId];
+  if (subject === void 0) return null;
+  const subjectTokens = new Set(tokenize(subject.rule));
+  if (subjectTokens.size === 0) return null;
+  let best = null;
+  for (const [id, other] of Object.entries(graph.lessons)) {
+    if (id === lessonId || other.status !== "active") continue;
+    const otherTokens = new Set(tokenize(other.rule));
+    if (otherTokens.size === 0) continue;
+    const score = jaccard(subjectTokens, otherTokens);
+    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
+      best = { id, score };
     }
-  };
+  }
+  if (best === null) return null;
   return {
-    // The input is matched in full (no truncation — truncation would miss suffix
-    // matches and let `$` falsely match an invented endpoint). Work is bounded by
-    // the shared budget instead: when it runs out we report a safe non-match.
-    test(input, budget) {
-      const b = budget ?? { remaining: Number.POSITIVE_INFINITY };
-      if (b.remaining <= 0) return false;
-      let current = /* @__PURE__ */ new Set();
-      for (let pos = 0; pos <= input.length; pos += 1) {
-        closure(current, start, input, pos, b);
-        if (current.has(accept)) return true;
-        if (b.remaining <= 0) return false;
-        if (pos === input.length) break;
-        const ch = input[pos];
-        const next = /* @__PURE__ */ new Set();
-        for (const s of current) {
-          b.remaining -= 1;
-          for (const t of states[s].chars) {
-            if (t.test(ch)) closure(next, t.target, input, pos + 1, b);
-          }
-        }
-        current = next;
-      }
-      return current.has(accept);
-    }
+    code: "NEAR_DUPLICATE_LESSON",
+    message: `Lesson "${lessonId}" closely resembles active lesson "${best.id}" (~${Math.round(best.score * 100)}% token overlap); consider updating "${best.id}" instead of adding a paraphrase (recall would surface both).`
   };
 }
+function jaccard(a, b) {
+  let intersection = 0;
+  for (const t of a) if (b.has(t)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
+}
 
-// src/lessons/regex-linear/ast.ts
-var UnsupportedRegexError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "UnsupportedRegexError";
+// src/core/errors.ts
+var AgentsMeshError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "AgentsMeshError";
+    this.code = code;
+  }
+};
+var LockAcquisitionError = class extends AgentsMeshError {
+  lockPath;
+  holder;
+  /** Human-readable lock name surfaced in the message, e.g. "lessons lock". */
+  label;
+  constructor(lockPath, holder, options) {
+    const label = options?.label ?? "lock";
+    super(
+      "AM_LOCK_ACQUISITION_FAILED",
+      `Could not acquire ${label} at ${lockPath}: currently held by ${holder}. Wait for the other process to finish, or remove ${lockPath} manually if you are sure no agentsmesh process is running.`,
+      options
+    );
+    this.name = "LockAcquisitionError";
+    this.lockPath = lockPath;
+    this.holder = holder;
+    this.label = label;
+  }
+};
+var FileSystemError = class extends AgentsMeshError {
+  path;
+  errnoCode;
+  constructor(path, message, options) {
+    super("AM_FILESYSTEM", message, options);
+    this.name = "FileSystemError";
+    this.path = path;
+    this.errnoCode = options?.errnoCode;
   }
 };
 
-// src/lessons/regex-linear/parse-helpers.ts
-var MAX_REPEAT = 1e3;
-var isWord = (c) => /[A-Za-z0-9_]/.test(c);
-function expandRepeat(atom, min, max) {
-  const items = [];
-  for (let k = 0; k < min; k += 1) items.push(atom);
-  if (max === Infinity) {
-    items.push({ k: "star", node: atom });
-  } else {
-    for (let k = min; k < max; k += 1) items.push({ k: "opt", node: atom });
+// src/utils/filesystem/process-lock.ts
+var DEFAULT_STALE_MS = 6 * 60 * 60 * 1e3;
+var DEFAULT_RETRIES = 30;
+var DEFAULT_RETRY_DELAY_MS = 200;
+var YOUNG_LOCK_GRACE_MS = 2e3;
+async function acquireProcessLock(lockPath, opts = {}) {
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const delay = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const stale = opts.staleMs ?? DEFAULT_STALE_MS;
+  await mkdir(dirname(lockPath), { recursive: true });
+  let attempt = 0;
+  while (true) {
+    const acquired = await tryAcquire(lockPath);
+    if (acquired) return acquired;
+    const existing = await inspectLock(lockPath);
+    if (existing !== "young" && isStale(existing, stale)) {
+      await rm(lockPath, { recursive: true, force: true }).catch(() => {
+      });
+      continue;
+    }
+    if (attempt >= retries) {
+      const holder = existing === "young" ? null : existing;
+      throw new LockAcquisitionError(lockPath, describeHolder(holder), { label: opts.label });
+    }
+    attempt++;
+    await sleep(delay);
   }
-  if (items.length === 0) return { k: "empty" };
-  return items.length === 1 ? items[0] : { k: "concat", items };
 }
-function escapeClass(c) {
-  switch (c) {
-    case "d":
-      return (x) => x >= "0" && x <= "9";
-    case "D":
-      return (x) => !(x >= "0" && x <= "9");
-    case "w":
-      return isWord;
-    case "W":
-      return (x) => !isWord(x);
-    case "s":
-      return (x) => /\s/.test(x);
-    case "S":
-      return (x) => !/\s/.test(x);
-    default:
-      return null;
+async function tryAcquire(lockPath) {
+  try {
+    await mkdir(lockPath, { recursive: false });
+  } catch (err) {
+    if (err.code === "EEXIST") return null;
+    throw err;
+  }
+  const metadataPath = join(lockPath, "holder.json");
+  const metadata = {
+    pid: process.pid,
+    started: Date.now(),
+    hostname: getHostname()
+  };
+  await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
+  let released = false;
+  const cleanup = () => {
+    if (released) return;
+    released = true;
+    try {
+      rmSync(lockPath, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  const signalHandler = (signal) => {
+    cleanup();
+    process.kill(process.pid, signal);
+  };
+  process.once("SIGINT", signalHandler);
+  process.once("SIGTERM", signalHandler);
+  process.once("exit", cleanup);
+  return async () => {
+    if (released) return;
+    released = true;
+    process.off("SIGINT", signalHandler);
+    process.off("SIGTERM", signalHandler);
+    process.off("exit", cleanup);
+    await rm(lockPath, { recursive: true, force: true }).catch(() => {
+    });
+  };
+}
+async function inspectLock(lockPath) {
+  try {
+    const raw = await readFile(join(lockPath, "holder.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!isLockMetadata(parsed)) return null;
+    return parsed;
+  } catch {
+    try {
+      const info = await stat(lockPath);
+      const ageMs = Date.now() - info.mtimeMs;
+      if (ageMs < YOUNG_LOCK_GRACE_MS) return "young";
+    } catch {
+    }
+    return null;
   }
 }
-var HEX2 = /^[0-9a-fA-F]{2}$/;
-var HEX4 = /^[0-9a-fA-F]{4}$/;
-function readUnicodeEscape(src, i, c) {
-  if (c === "x") {
-    const hex2 = src.slice(i, i + 2);
-    return HEX2.test(hex2) ? { ch: String.fromCharCode(parseInt(hex2, 16)), len: 2 } : { ch: "x", len: 0 };
-  }
-  const hex = src.slice(i, i + 4);
-  return HEX4.test(hex) ? { ch: String.fromCharCode(parseInt(hex, 16)), len: 4 } : { ch: "u", len: 0 };
+function isStale(meta, staleMs) {
+  if (!meta) return true;
+  const sameHost = !meta.hostname || meta.hostname === getHostname();
+  if (sameHost && !isProcessAlive(meta.pid)) return true;
+  return Date.now() - meta.started > staleMs;
 }
-function readControlEscape(src, i) {
-  const x = src[i];
-  if (x === void 0 || !/[A-Za-z]/.test(x)) {
-    throw new UnsupportedRegexError("\\c must be followed by a letter");
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
   }
-  return { ch: String.fromCharCode(x.charCodeAt(0) & 31), len: 1 };
 }
-function classEscapeChar(src, i, e) {
-  if (e === "b") return { ch: "\b", len: 0 };
-  if (e === "c") return readControlEscape(src, i);
-  if (e === "x" || e === "u") return readUnicodeEscape(src, i, e);
-  return { ch: escapeLiteral(e), len: 0 };
+function describeHolder(meta) {
+  if (!meta) return "unknown (unreadable lock metadata)";
+  const host = meta.hostname ? `${meta.hostname}:` : "";
+  return `${host}pid ${meta.pid} (running ${Date.now() - meta.started}ms)`;
 }
-function escapeLiteral(c) {
-  switch (c) {
-    case "t":
-      return "	";
-    case "n":
-      return "\n";
-    case "r":
-      return "\r";
-    case "f":
-      return "\f";
-    case "v":
-      return "\v";
-    case "0":
-      return "\0";
-    default:
-      return c;
-  }
+function isLockMetadata(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.pid === "number" && typeof v.started === "number";
+}
+function getHostname() {
+  return hostname();
+}
+function sleep(ms) {
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
-// src/lessons/regex-linear/parse.ts
-function parseRegex(src) {
-  let i = 0;
-  const peek = () => src[i];
-  const eat = () => src[i++];
-  function parseAlt() {
-    const opts = [parseConcat()];
-    while (peek() === "|") {
-      i += 1;
-      opts.push(parseConcat());
+// src/lessons/lessons-lock.ts
+var LESSONS_LOCK_FILENAME = ".lessons.lock";
+function lessonsLockPath(projectRoot) {
+  return resolve(projectRoot, ".agentsmesh/lessons", LESSONS_LOCK_FILENAME);
+}
+async function acquireLessonsLock(projectRoot, opts = {}) {
+  const lockPath = lessonsLockPath(projectRoot);
+  await mkdir(dirname(lockPath), { recursive: true });
+  return acquireProcessLock(lockPath, { ...opts, label: "lessons lock" });
+}
+
+// src/lessons/validate-checks.ts
+function collectDanglingRefs(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    for (const topicId of lesson.topics) {
+      if (graph.topics[topicId] === void 0) {
+        findings.push({
+          level: "error",
+          code: "DANGLING_TOPIC",
+          message: `Lesson "${lessonId}" references unknown topic "${topicId}".`,
+          lessonId,
+          topicId
+        });
+      }
     }
-    return opts.length === 1 ? opts[0] : { k: "alt", opts };
-  }
-  function parseConcat() {
-    const items = [];
-    while (i < src.length && peek() !== "|" && peek() !== ")") {
-      items.push(parseQuantified());
+    for (const triggerId of lesson.triggers) {
+      if (graph.triggers[triggerId] === void 0) {
+        findings.push({
+          level: "error",
+          code: "DANGLING_TRIGGER",
+          message: `Lesson "${lessonId}" references unknown trigger "${triggerId}".`,
+          lessonId,
+          triggerId
+        });
+      }
+    }
+    if (lesson.supersededBy !== void 0 && graph.lessons[lesson.supersededBy] === void 0) {
+      findings.push({
+        level: "error",
+        code: "DANGLING_SUPERSEDER",
+        message: `Lesson "${lessonId}" supersededBy unknown lesson "${lesson.supersededBy}".`,
+        lessonId
+      });
     }
-    if (items.length === 0) return { k: "empty" };
-    return items.length === 1 ? items[0] : { k: "concat", items };
   }
-  function parseQuantified() {
-    const atom = parseAtom();
-    const q = peek();
-    if (q === "*" || q === "+" || q === "?") {
-      i += 1;
-      if (peek() === "?") i += 1;
-      return q === "*" ? { k: "star", node: atom } : q === "+" ? { k: "plus", node: atom } : { k: "opt", node: atom };
+}
+function collectDuplicateRefs(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    for (const topicId of firstDuplicates(lesson.topics)) {
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TOPIC_REF",
+        message: `Lesson "${lessonId}" references topic "${topicId}" more than once.`,
+        lessonId,
+        topicId
+      });
     }
-    if (q === "{") {
-      const repeat = tryParseBrace();
-      if (repeat !== null) return expandRepeat(atom, repeat.min, repeat.max);
+    for (const triggerId of firstDuplicates(lesson.triggers)) {
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TRIGGER_REF",
+        message: `Lesson "${lessonId}" references trigger "${triggerId}" more than once.`,
+        lessonId,
+        triggerId
+      });
     }
-    return atom;
   }
-  function tryParseBrace() {
-    const m = /^\{(\d+)(,(\d*)?)?\}/.exec(src.slice(i));
-    if (m === null) return null;
-    i += m[0].length;
-    if (peek() === "?") i += 1;
-    const min = Number(m[1]);
-    const max = m[2] === void 0 ? min : m[3] === "" || m[3] === void 0 ? Infinity : Number(m[3]);
-    if (min > MAX_REPEAT || max !== Infinity && max > MAX_REPEAT) {
-      throw new UnsupportedRegexError(`Repeat count over ${MAX_REPEAT} not supported: {${m[1]}\u2026}`);
-    }
-    return { min, max };
+}
+function firstDuplicates(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const dup = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (seen.has(id)) dup.add(id);
+    else seen.add(id);
   }
-  function parseAtom() {
-    const c = peek();
-    if (c === "(") return parseGroup();
-    if (c === "[") return parseClass();
-    if (c === "\\") return parseEscape();
-    if (c === ".") {
-      i += 1;
-      return { k: "any" };
-    }
-    if (c === "^") {
-      i += 1;
-      return { k: "assert", kind: "start" };
-    }
-    if (c === "$") {
-      i += 1;
-      return { k: "assert", kind: "end" };
-    }
-    if (c === void 0 || c === "*" || c === "+" || c === "?" || c === ")") {
-      throw new UnsupportedRegexError(`Unexpected '${c ?? "<end>"}' in pattern`);
+  return [...dup];
+}
+function collectStatusInvariants(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status === "superseded" && lesson.supersededBy === void 0) {
+      findings.push({
+        level: "error",
+        code: "SUPERSEDED_WITHOUT_TARGET",
+        message: `Lesson "${lessonId}" has status "superseded" but no supersededBy target.`,
+        lessonId
+      });
     }
-    i += 1;
-    return { k: "char", ch: c };
-  }
-  function parseGroup() {
-    i += 1;
-    if (peek() === "?") {
-      const c2 = src[i + 1];
-      if (c2 === "=" || c2 === "!" || c2 === "<") {
-        if (!(c2 === "<" && /[A-Za-z]/.test(src[i + 2] ?? ""))) {
-          throw new UnsupportedRegexError("Lookaround assertions are not supported");
-        }
-      }
-      if (c2 === ":") i += 2;
-      else if (c2 === "<") {
-        i += 2;
-        while (i < src.length && src[i] !== ">") i += 1;
-        i += 1;
-      }
+    if (lesson.status === "active" && lesson.supersededBy !== void 0) {
+      findings.push({
+        level: "error",
+        code: "ACTIVE_WITH_SUPERSEDER",
+        message: `Lesson "${lessonId}" has status "active" but declares supersededBy.`,
+        lessonId
+      });
     }
-    const inner = parseAlt();
-    if (peek() !== ")") throw new UnsupportedRegexError("Unbalanced group");
-    i += 1;
-    return inner;
   }
-  function parseEscape() {
-    i += 1;
-    const c = peek();
-    if (c === void 0) throw new UnsupportedRegexError("Trailing backslash");
-    if (/[1-9]/.test(c) || c === "k")
-      throw new UnsupportedRegexError("Backreferences are not supported");
-    i += 1;
-    if (c === "b") return { k: "assert", kind: "wordB" };
-    if (c === "B") return { k: "assert", kind: "nonWordB" };
-    const cls = escapeClass(c);
-    if (cls !== null) return { k: "class", test: cls };
-    if (c === "x" || c === "u" || c === "c") {
-      const { ch, len } = c === "c" ? readControlEscape(src, i) : readUnicodeEscape(src, i, c);
-      i += len;
-      return { k: "char", ch };
+}
+function collectLifecycleInvariants(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.supersededBy === void 0) continue;
+    if (lesson.supersededBy === lessonId) {
+      findings.push({
+        level: "error",
+        code: "SELF_SUPERSEDED",
+        message: `Lesson "${lessonId}" is superseded by itself.`,
+        lessonId
+      });
+      continue;
     }
-    return { k: "char", ch: escapeLiteral(c) };
-  }
-  function parseClass() {
-    i += 1;
-    const negate = peek() === "^";
-    if (negate) i += 1;
-    const tests = [];
-    while (i < src.length && peek() !== "]") {
-      tests.push(parseClassMember());
+    const target = graph.lessons[lesson.supersededBy];
+    if (target !== void 0 && target.status !== "active") {
+      findings.push({
+        level: "error",
+        code: "INACTIVE_SUPERSEDER",
+        message: `Lesson "${lessonId}" is superseded by "${lesson.supersededBy}", which is itself ${target.status} \u2014 the chain dead-ends with no live replacement.`,
+        lessonId
+      });
     }
-    if (peek() !== "]") throw new UnsupportedRegexError("Unterminated character class");
-    i += 1;
-    const base = (c) => tests.some((t) => t(c));
-    return { k: "class", test: negate ? (c) => !base(c) : base };
   }
-  function parseClassMember() {
-    let lo;
-    if (peek() === "\\") {
-      i += 1;
-      const e = eat();
-      const cls = escapeClass(e);
-      if (cls !== null) return cls;
-      const r = classEscapeChar(src, i, e);
-      i += r.len;
-      lo = r.ch;
-    } else {
-      lo = eat();
-    }
-    if (peek() === "-" && src[i + 1] !== void 0 && src[i + 1] !== "]") {
-      i += 1;
-      let hi;
-      if (peek() === "\\") {
-        i += 1;
-        const e2 = eat();
-        const r = classEscapeChar(src, i, e2);
-        i += r.len;
-        hi = r.ch;
-      } else {
-        hi = eat();
+  collectSupersedeCycles(graph, findings);
+}
+function collectSupersedeCycles(graph, findings) {
+  const reported = /* @__PURE__ */ new Set();
+  for (const startId of Object.keys(graph.lessons)) {
+    const seen = /* @__PURE__ */ new Set();
+    let cur = startId;
+    while (cur !== void 0) {
+      if (seen.has(cur)) {
+        if (cur !== startId || reported.has(cur)) break;
+        reported.add(cur);
+        findings.push({
+          level: "error",
+          code: "SUPERSEDE_CYCLE",
+          message: `Lesson "${startId}" is part of a supersededBy cycle.`,
+          lessonId: startId
+        });
+        break;
       }
-      const a = lo.codePointAt(0);
-      const b = hi.codePointAt(0);
-      return (c) => {
-        const p = c.codePointAt(0);
-        return p >= a && p <= b;
-      };
+      seen.add(cur);
+      const next = graph.lessons[cur]?.supersededBy;
+      if (next === cur) break;
+      cur = next;
     }
-    return (c) => c === lo;
   }
-  const ast = parseAlt();
-  if (i !== src.length) throw new UnsupportedRegexError(`Unexpected '${peek()}' at ${i}`);
-  return ast;
 }
-
-// src/lessons/regex-linear/index.ts
-var cache = /* @__PURE__ */ new Map();
-function compileLinearMatcher(pattern) {
-  const hit = cache.get(pattern);
-  if (hit !== void 0 || cache.has(pattern)) return hit ?? null;
-  let matcher;
-  try {
-    matcher = buildMatcher(parseRegex(pattern));
-  } catch {
-    matcher = null;
+function collectReachability(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status === "active" && lesson.triggers.length === 0) {
+      findings.push({
+        level: "warning",
+        code: "UNREACHABLE_LESSON",
+        message: `Active lesson "${lessonId}" has no triggers and can never be recalled.`,
+        lessonId
+      });
+    }
   }
-  cache.set(pattern, matcher);
-  return matcher;
-}
-
-// src/lessons/regex-safety.ts
-var MAX_PATTERN_LENGTH = 1e3;
-function isSafeRegexPattern(pattern) {
-  if (pattern.length > MAX_PATTERN_LENGTH) return false;
-  return compileLinearMatcher(pattern) !== null;
 }
-function getCommandMatcher(pattern) {
-  if (pattern.length > MAX_PATTERN_LENGTH) return null;
-  return compileLinearMatcher(pattern);
+function collectOrphans(graph, findings) {
+  const referencedTopics = /* @__PURE__ */ new Set();
+  const referencedTriggers = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    for (const t of lesson.topics) referencedTopics.add(t);
+    for (const t of lesson.triggers) referencedTriggers.add(t);
+  }
+  for (const topicId of Object.keys(graph.topics)) {
+    if (!referencedTopics.has(topicId)) {
+      findings.push({
+        level: "warning",
+        code: "ORPHAN_TOPIC",
+        message: `Topic "${topicId}" is not referenced by any lesson.`,
+        topicId
+      });
+    }
+  }
+  for (const triggerId of Object.keys(graph.triggers)) {
+    if (!referencedTriggers.has(triggerId)) {
+      findings.push({
+        level: "warning",
+        code: "ORPHAN_TRIGGER",
+        message: `Trigger "${triggerId}" is not referenced by any lesson.`,
+        triggerId
+      });
+    }
+  }
 }
 
 // src/lessons/validate-quality.ts
@@ -1410,6 +1579,11 @@ function collectFanout(graph, findings) {
     });
   }
 }
+function normalizeRule2(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+// src/lessons/validate-keywords.ts
 function collectLowSignalKeywords(graph, findings) {
   const activeTriggerIds2 = /* @__PURE__ */ new Set();
   for (const lesson of Object.values(graph.lessons)) {
@@ -1423,7 +1597,7 @@ function collectLowSignalKeywords(graph, findings) {
     findings.push({
       level: "warning",
       code: "LOW_SIGNAL_KEYWORD",
-      message: `Keyword trigger "${triggerId}" carries more than ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens (${trigger.pattern}); recall matches a keyword only as a substring of --keyword or a contiguous token-run in the file/command, so it rarely fires \u2014 use a short distinctive phrase.`,
+      message: `Keyword trigger "${triggerId}" carries more than ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens (${trigger.pattern}); recall matches a keyword only as a contiguous token-run in --keyword or the file/command, so it rarely fires \u2014 use a short distinctive phrase.`,
       triggerId
     });
   }
@@ -1448,9 +1622,6 @@ function collectStopwordKeywords(graph, findings) {
     });
   }
 }
-function normalizeRule2(rule) {
-  return rule.trim().replace(/\s+/g, " ").toLowerCase();
-}
 
 // src/lessons/validate.ts
 function validateLessonsGraph(graph, options = {}) {
@@ -1478,6 +1649,8 @@ function validateLessonsGraph(graph, options = {}) {
   collectLowSignalKeywords(graph, findings);
   collectStopwordKeywords(graph, findings);
   collectRunnerAnchoredPatterns(graph, findings);
+  collectBroadCommandPatterns(graph, findings);
+  collectBroadFileGlobs(graph, findings);
   if (options.knownPaths !== void 0) collectDeadFileGlobs(graph, findings, options.knownPaths);
   const ok = findings.every((f) => f.level !== "error");
   return { ok, findings };
@@ -1521,52 +1694,7 @@ async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
   return mutateLessonsGraphLocked(projectRoot, mutator, options);
 }
 
-// src/lessons/trigger-effectiveness.ts
-function ineffectiveTriggers(graph, triggerIds) {
-  const out = [];
-  for (const id of triggerIds) {
-    const trigger = graph.triggers[id];
-    if (trigger === void 0) continue;
-    const reason = ineffectiveReason(trigger.kind, trigger.pattern);
-    if (reason !== null) out.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
-  }
-  return out;
-}
-function ineffectiveReason(kind, pattern) {
-  if (kind === "keyword") {
-    if (tokenize(pattern).length === 0) {
-      return "keyword has no matchable token after stopword filtering \u2014 it cannot fire on the mandatory --file/--cmd recall path";
-    }
-    if (keywordNeedleLosesTokens(pattern)) {
-      return "keyword contains stopwords/short words, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path";
-    }
-    return null;
-  }
-  if (kind === "command_pattern") {
-    let valid = true;
-    try {
-      new RegExp(pattern);
-    } catch {
-      valid = false;
-    }
-    if (!valid) {
-      return "invalid regex \u2014 recall compiles it with new RegExp and swallows the throw as a non-match, so it never fires";
-    }
-    if (!isSafeRegexPattern(pattern)) {
-      return "regex is outside the provably-linear engine \u2014 recall skips it (ReDoS guard), so it never fires";
-    }
-    return null;
-  }
-  return null;
-}
-function blockingDeadTriggers(graph, triggerIds) {
-  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
-}
-
 // src/lessons/add.ts
-function countInputTriggers(triggers) {
-  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
-}
 async function addLesson(projectRoot, input, options = {}) {
   return mutateLessonsGraph(projectRoot, (graph) => addLessonInto(graph, input, options), {
     retries: options.retries
@@ -1574,10 +1702,7 @@ async function addLesson(projectRoot, input, options = {}) {
 }
 function addLessonInto(graph, input, options) {
   const ruleKey = normalizeRule(input.rule);
-  const trimmedRule = input.rule.trim();
-  if (trimmedRule.length > MAX_RULE_LENGTH) {
-    throw new RuleTooLongError(trimmedRule.length, MAX_RULE_LENGTH);
-  }
+  const trimmedRule = assertRuleShape(input.rule);
   const existingId = findExistingLessonByRule(graph, ruleKey);
   const isNewTopic = graph.topics[input.topic] === void 0;
   if (isNewTopic) {
@@ -1587,29 +1712,23 @@ function addLessonInto(graph, input, options) {
     }
     graph.topics[input.topic] = { summary: options.topicSummary };
   }
-  const skipTriggerGates = options.allowNoTrigger === true || input.scope === "always";
-  if (!skipTriggerGates) {
-    const existingTriggers = existingId !== null ? graph.lessons[existingId]?.triggers.length ?? 0 : 0;
-    if (countInputTriggers(input.triggers) === 0 && existingTriggers === 0) {
-      throw new NoTriggerError();
-    }
-  }
+  const existing = existingId !== null ? graph.lessons[existingId] : void 0;
+  assertTriggerInputs(input, options, existing?.triggers.length ?? 0);
   const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
-  if (!skipTriggerGates) {
-    const resultingTriggers = existingId !== null ? union(graph.lessons[existingId].triggers, triggerIds) : triggerIds;
-    const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
-    if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
-      throw new UnrecallableLessonError(blockingDead);
-    }
+  if (!skipsTriggerGates(input, options)) {
+    assertRecallable(
+      graph,
+      existing === void 0 ? triggerIds : union(existing.triggers, triggerIds)
+    );
   }
   if (existingId !== null) {
-    const existing = graph.lessons[existingId];
+    const existing2 = graph.lessons[existingId];
     graph.lessons[existingId] = {
-      ...existing,
-      topics: union(existing.topics, [input.topic]),
-      triggers: union(existing.triggers, triggerIds),
-      evidence: union(existing.evidence, input.evidence ?? []),
-      ...existing.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
+      ...existing2,
+      topics: union(existing2.topics, [input.topic]),
+      triggers: union(existing2.triggers, triggerIds),
+      evidence: union(existing2.evidence, input.evidence ?? []),
+      ...existing2.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
       // Re-capturing a rule with --scope always promotes it to always-on.
       ...input.scope === "always" ? { scope: "always" } : {}
     };
@@ -1814,14 +1933,16 @@ function deriveHaystackTokens(query) {
   if (query.command !== void 0) parts.push(query.command);
   if (parts.length === 0) return [];
   const out = [];
-  for (const raw of parts.join(" ").split(/[^A-Za-z0-9]+/)) {
-    if (raw.length === 0) continue;
+  for (const raw of splitTokens(parts.join(" "))) {
     out.push(raw.toLowerCase());
     const sub = raw.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(" ").filter((t) => t.length > 0);
     if (sub.length > 1) out.push(...sub);
   }
   return out;
 }
+function splitTokens(text) {
+  return text.split(/[^A-Za-z0-9]+/).filter((t) => t.length > 0);
+}
 function containsRun(needle, hay) {
   if (needle.length === 0) return false;
   for (let i = 0; i + needle.length <= hay.length; i += 1) {
@@ -1837,10 +1958,11 @@ function containsRun(needle, hay) {
   return false;
 }
 function keywordMatches(pattern, query) {
-  if (query.keyword !== void 0 && query.keyword.toLowerCase().includes(pattern.toLowerCase())) {
+  const needle = tokenize(pattern);
+  if (query.keyword !== void 0 && containsRun(needle, splitTokens(query.keyword.toLowerCase()))) {
     return true;
   }
-  return containsRun(tokenize(pattern), deriveHaystackTokens(query));
+  return containsRun(needle, deriveHaystackTokens(query));
 }
 
 // src/lessons/query.ts
@@ -2043,6 +2165,15 @@ function buildFanout(graph) {
   }
   return fanout;
 }
+var KEYWORD_NARROWNESS = 0.4;
+function buildNarrowness(graph) {
+  const narrowness = /* @__PURE__ */ new Map();
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind === "file_glob") narrowness.set(id, globNarrowness(trigger.pattern));
+    else narrowness.set(id, trigger.kind === "keyword" ? KEYWORD_NARROWNESS : 1);
+  }
+  return narrowness;
+}
 function buildTopicCoherence(matches) {
   const topicCount = /* @__PURE__ */ new Map();
   for (const { lesson } of matches) {
@@ -2061,7 +2192,7 @@ function buildTopicCoherence(matches) {
 var DEFAULT_RECALL_LIMIT = 10;
 var DEFAULT_RECALL_MAX_TOKENS = 400;
 var RRF_K = 60;
-var SPECIFICITY_WEIGHT = 3;
+var SPECIFICITY_WEIGHT = 5;
 var TOPIC_COHERENCE_WEIGHT = 2;
 var BM25_WEIGHT = 1;
 var EFFECTIVENESS_WEIGHT = 1;
@@ -2088,12 +2219,15 @@ function rankLessons(graph, query, matches, options = {}) {
   const terms = queryTerms(query);
   const corpus = buildCorpus(graph);
   const fanout = buildFanout(graph);
+  const narrowness = buildNarrowness(graph);
   const coherence = buildTopicCoherence(matches);
   const matchedTriggerIds = collectMatchedTriggerIds(graph, query);
   const scored = matches.map(({ id, lesson }) => {
     const hitTriggers = lesson.triggers.filter((t) => matchedTriggerIds.has(t));
     let specificity = 0;
-    for (const t of hitTriggers) specificity = Math.max(specificity, 1 / fanout.get(t));
+    for (const t of hitTriggers) {
+      specificity = Math.max(specificity, (narrowness.get(t) ?? 1) / fanout.get(t));
+    }
     return {
       id,
       lesson,
@@ -2710,9 +2844,9 @@ var LINE_REFS = String.raw`L\d+(?:\s*,\s*L\d+)*`;
 var LINE_REF_PATTERNS = [
   new RegExp(String.raw`\s*\bSee\s+${LINE_REFS}\.?`, "g"),
   // " See L128." / " See L140, L149"
-  new RegExp(String.raw`\s*\((?:${LINE_REFS})\)\.?`, "g"),
+  new RegExp(String.raw`\s*\((?:${LINE_REFS})\)`, "g"),
   // " (L174)" / " (L92, L163)"
-  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]\.?`, "g")
+  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]`, "g")
   // " [L161, L208]"
 ];
 var ALSO_RELEVANT_PATTERN = /\s*\(also relevant[^)]*\)\s*/g;
@@ -2950,6 +3084,32 @@ function isCoveredByExisting(candidate, existing) {
   }
   return false;
 }
+var OPENER = /^---[ \t]*\r?\n/;
+var CLOSER = /^---[ \t]*\r?$/m;
+function splitFrontmatter(content) {
+  const opener = OPENER.exec(content);
+  if (opener === null) return null;
+  const yamlStart = opener[0].length;
+  const closer = CLOSER.exec(content.slice(yamlStart));
+  if (closer === null) return null;
+  const closeStart = yamlStart + closer.index;
+  const closeEnd = closeStart + closer[0].length;
+  return {
+    yaml: content.slice(yamlStart, closeStart),
+    body: content.slice(closeEnd).trim(),
+    prefix: content.slice(0, closeEnd)
+  };
+}
+function serializeFrontmatter(frontmatter, body) {
+  const keys = Object.keys(frontmatter);
+  if (keys.length === 0) return body;
+  const yamlStr = stringify(frontmatter, { lineWidth: 0 }).trimEnd();
+  return `---
+${yamlStr}
+---
+
+${body}`;
+}
 var LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
 var LESSONS_CONTRACT_END = "<!-- agentsmesh:lessons-contract:end -->";
 function escapeRegExp(value) {
@@ -2962,10 +3122,8 @@ function stripManagedBlock(content, start, end) {
   return content.replace(managedBlockPattern(start, end), "").trim();
 }
 function splitFrontmatterPrefix(content) {
-  if (content.indexOf("---") !== 0) return { prefix: "", body: content.trim() };
-  const close = content.indexOf("---", 3);
-  if (close === -1) return { prefix: "", body: content.trim() };
-  return { prefix: content.slice(0, close + 3), body: content.slice(close + 3).trim() };
+  const split = splitFrontmatter(content);
+  return split === null ? { prefix: "", body: content.trim() } : { prefix: split.prefix, body: split.body };
 }
 function insertAtBodyTop(content, block) {
   const { prefix, body } = splitFrontmatterPrefix(content);
@@ -3019,16 +3177,6 @@ ${rule}`, "").replace(rule, ""),
     content
   );
 }
-function serializeFrontmatter(frontmatter, body) {
-  const keys = Object.keys(frontmatter);
-  if (keys.length === 0) return body;
-  const yamlStr = stringify(frontmatter, { lineWidth: 0 }).trimEnd();
-  return `---
-${yamlStr}
----
-
-${body}`;
-}
 
 // src/lessons/skill.ts
 var LESSONS_SKILL_NAME = "lessons";