agentsmesh 0.21.0 → 0.23.0

package/dist/lessons.js

@@ -0,0 +1,2764 @@
+import { z } from 'zod';
+import { createHash } from 'crypto';
+import picomatch from 'picomatch';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, renameSync, readdirSync, realpathSync, appendFileSync, statSync } from 'fs';
+import { resolve, join, relative, sep, dirname, basename, extname } from 'path';
+import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
+import { mkdir, rm, writeFile, readFile, stat, lstat, unlink, rename, chmod } from 'fs/promises';
+import { tmpdir, hostname } from 'os';
+import 'timers/promises';
+
+// src/lessons/graph-schema.ts
+var CURRENT_GRAPH_VERSION = 1;
+var MAX_RULE_LENGTH = 2e3;
+var IdSchema = z.string().regex(/^[a-z0-9-]+$/, "id must be kebab-case");
+var DateSchema = z.string().regex(
+  /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z?)?$/,
+  "createdAt must be ISO-8601 date or datetime"
+);
+var TopicSchema = z.object({
+  summary: z.string().min(1, "topic summary must not be empty")
+}).strict();
+var TriggerKindSchema = z.enum(["file_glob", "command_pattern", "keyword"]);
+var TriggerSchema = z.object({
+  kind: TriggerKindSchema,
+  pattern: z.string().min(1, "trigger pattern must not be empty")
+}).strict();
+var LessonStatusSchema = z.enum(["active", "deprecated", "superseded"]);
+var LessonSchema = z.object({
+  rule: z.string().min(1, "lesson rule must not be empty"),
+  rationale: z.string().min(1).optional(),
+  topics: z.array(IdSchema).min(1, "lesson must reference at least one topic"),
+  triggers: z.array(IdSchema),
+  evidence: z.array(z.string().min(1)),
+  status: LessonStatusSchema,
+  supersededBy: IdSchema.optional(),
+  createdAt: DateSchema
+}).strict();
+var LessonsGraphSchema = z.object({
+  version: z.literal(CURRENT_GRAPH_VERSION),
+  lessons: z.record(IdSchema, LessonSchema),
+  topics: z.record(IdSchema, TopicSchema),
+  triggers: z.record(IdSchema, TriggerSchema)
+}).strict();
+function parseGraph(raw) {
+  return LessonsGraphSchema.parse(raw);
+}
+function normalizeRule(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function union(base, extra) {
+  const out = [...base];
+  for (const item of extra) if (!out.includes(item)) out.push(item);
+  return out;
+}
+function mergeTriggers(graph, spec) {
+  const requested = [
+    // Normalize `\` → `/` so a Windows-shaped glob matches: recall relativizes
+    // every `--file` to forward slashes (normalizeRecallFile), so a backslash
+    // pattern stored raw would silently never fire. Normalizing here also lets
+    // a backslash pattern dedupe against the forward-slash node it equals.
+    ...(spec.files ?? []).map(
+      (p) => ({ kind: "file_glob", pattern: p.replaceAll("\\", "/") })
+    ),
+    ...(spec.commands ?? []).map((p) => ({ kind: "command_pattern", pattern: p })),
+    ...(spec.keywords ?? []).map((p) => ({ kind: "keyword", pattern: p }))
+  ];
+  const reverseLookup = /* @__PURE__ */ new Map();
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    reverseLookup.set(triggerKey(trigger), id);
+  }
+  const triggerIds = [];
+  const newTriggerIds = [];
+  for (const spec2 of requested) {
+    const key = triggerKey(spec2);
+    const existing = reverseLookup.get(key);
+    if (existing !== void 0) {
+      if (!triggerIds.includes(existing)) triggerIds.push(existing);
+      continue;
+    }
+    const id = makeTriggerId(spec2);
+    graph.triggers[id] = { kind: spec2.kind, pattern: spec2.pattern };
+    reverseLookup.set(key, id);
+    triggerIds.push(id);
+    newTriggerIds.push(id);
+  }
+  return { triggerIds, newTriggerIds };
+}
+function triggerKey(t) {
+  return `${t.kind}|${t.pattern}`;
+}
+var TRIGGER_PREFIX = {
+  file_glob: "glob",
+  command_pattern: "cmd",
+  keyword: "kw"
+};
+function makeTriggerId(spec) {
+  const hash = createHash("sha1").update(triggerKey(spec)).digest("hex").slice(0, 8);
+  return `t-${TRIGGER_PREFIX[spec.kind]}-${hash}`;
+}
+function makeLessonId(graph, topic, ruleKey) {
+  const slug = ruleToSlug(ruleKey);
+  const base = slug.length > 0 ? `${topic}-${slug}` : `${topic}-${createHash("sha1").update(ruleKey).digest("hex").slice(0, 8)}`;
+  let candidate = base;
+  let i = 2;
+  while (graph.lessons[candidate] !== void 0) {
+    candidate = `${base}-${i}`;
+    i += 1;
+  }
+  return candidate;
+}
+function ruleToSlug(rule) {
+  const words = rule.replace(/[^a-z0-9 ]+/g, " ").split(/\s+/).filter((w) => w.length > 0).slice(0, 5);
+  return words.join("-").slice(0, 40).replace(/-+$/, "");
+}
+function todayIso() {
+  const now = /* @__PURE__ */ new Date();
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+// src/lessons/add-errors.ts
+var UnknownTopicError = class extends Error {
+  constructor(topic) {
+    super(`Unknown topic: ${topic}. Pass allowNewTopic + topicSummary to create it.`);
+    this.topic = topic;
+    this.name = "UnknownTopicError";
+  }
+  code = "UNKNOWN_TOPIC";
+};
+var RuleTooLongError = class extends Error {
+  constructor(length, max) {
+    super(
+      `Lesson rule is ${length} characters (max ${max}). A rule should be one imperative sentence \u2014 trim it to the essential instruction, or split it into separate lessons.`
+    );
+    this.length = length;
+    this.max = max;
+    this.name = "RuleTooLongError";
+  }
+  code = "OVERSIZED_RULE";
+};
+var NoTriggerError = class extends Error {
+  code = "NO_TRIGGER";
+  constructor() {
+    super(
+      "A lesson needs at least one trigger to be recallable. Pass --trigger-file <glob> (preferred), --trigger-cmd <regex>, or --trigger-kw <text>."
+    );
+    this.name = "NoTriggerError";
+  }
+};
+var UnrecallableLessonError = class extends Error {
+  constructor(deadTriggers) {
+    super(
+      "This capture would create a lesson with no effective trigger \u2014 every trigger is dead on the mandatory --file/--cmd recall path, so the lesson could never be recalled there:\n" + deadTriggers.map((t) => `  \u2022 ${t.kind} "${t.pattern}" \u2014 ${t.reason}`).join("\n") + '\nFix: add a precise --trigger-file <glob> (preferred) or a valid --trigger-cmd <regex>; for a keyword, drop the stopwords (e.g. "state art" not "state of the art").'
+    );
+    this.deadTriggers = deadTriggers;
+    this.name = "UnrecallableLessonError";
+  }
+  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);
+  }
+  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 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 score;
+}
+
+// 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;
+}
+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 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
+    });
+  }
+}
+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
+    });
+  }
+}
+
+// src/lessons/capture-guardrails.ts
+var NEAR_DUPLICATE_THRESHOLD = 0.6;
+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 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 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.`
+    });
+  }
+  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.`
+      });
+    }
+  }
+  return warnings;
+}
+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 {
+    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);
+}
+var GRAPH_REL_PATH = ".agentsmesh/lessons/lessons.json";
+function graphFilePath(projectRoot) {
+  return resolve(projectRoot, GRAPH_REL_PATH);
+}
+function loadLessonsGraph(projectRoot) {
+  const raw = readFileSync(graphFilePath(projectRoot), "utf8");
+  return parseGraph(JSON.parse(raw));
+}
+function tryLoadLessonsGraph(projectRoot) {
+  if (!existsSync(graphFilePath(projectRoot))) return null;
+  return loadLessonsGraph(projectRoot);
+}
+function loadLessonsGraphResilient(projectRoot) {
+  const path = graphFilePath(projectRoot);
+  if (!existsSync(path)) return { status: "absent", graph: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const version = parsed?.version;
+    if (typeof version === "number" && version > CURRENT_GRAPH_VERSION) {
+      return { status: "newer-version", graph: null, version };
+    }
+    return { status: "ok", graph: parseGraph(parsed) };
+  } catch (error) {
+    return {
+      status: "corrupt",
+      graph: null,
+      error: error instanceof Error ? error : new Error(String(error))
+    };
+  }
+}
+function saveLessonsGraph(projectRoot, graph) {
+  const path = graphFilePath(projectRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, serializeGraph(graph), "utf8");
+  renameSync(tmp, path);
+}
+function serializeGraph(graph) {
+  return `${JSON.stringify(canonicalize(graph), null, 2)}
+`;
+}
+function canonicalize(value) {
+  if (value === null) return null;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a < b ? -1 : 1
+    );
+    const out = {};
+    for (const [k, v] of entries) out[k] = canonicalize(v);
+    return out;
+  }
+  return value;
+}
+var LegacyTriggersSchema = z.object({
+  file_globs: z.array(z.string()),
+  command_patterns: z.array(z.string()),
+  keywords: z.array(z.string())
+}).refine((t) => t.file_globs.length + t.command_patterns.length + t.keywords.length > 0, {
+  message: "cluster must declare at least one trigger of any type"
+});
+var LegacyClusterSchema = z.object({
+  topic: z.string().regex(/^[a-z0-9-]+$/),
+  file: z.string().regex(/\.md$/),
+  summary: z.string().min(1),
+  triggers: LegacyTriggersSchema
+});
+var LegacyIndexSchema = z.object({
+  version: z.literal(1),
+  clusters: z.array(LegacyClusterSchema)
+});
+function collectClusterTriggerIds(cluster, triggersById, triggerIdByKey) {
+  const specs = [
+    ...cluster.triggers.file_globs.map((p) => ({ kind: "file_glob", pattern: p })),
+    ...cluster.triggers.command_patterns.map(
+      (p) => ({ kind: "command_pattern", pattern: p })
+    ),
+    ...cluster.triggers.keywords.map((p) => ({ kind: "keyword", pattern: p }))
+  ];
+  const ids = [];
+  for (const spec of specs) {
+    const key = `${spec.kind}|${spec.pattern}`;
+    let id = triggerIdByKey.get(key);
+    if (id === void 0) {
+      id = makeTriggerId2(spec);
+      triggerIdByKey.set(key, id);
+      triggersById.set(id, { kind: spec.kind, pattern: spec.pattern });
+    }
+    if (!ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+var TRIGGER_PREFIX2 = {
+  file_glob: "glob",
+  command_pattern: "cmd",
+  keyword: "kw"
+};
+function makeTriggerId2(spec) {
+  const hash = createHash("sha1").update(`${spec.kind}|${spec.pattern}`).digest("hex").slice(0, 8);
+  return `t-${TRIGGER_PREFIX2[spec.kind]}-${hash}`;
+}
+var RULE_HEADING_RE = /^##\s+Rules\b.*$/i;
+var NEXT_HEADING_RE = /^##\s+/;
+var RULE_LINE_RE = /^(\d+)\.\s+(.+?)\s*$/;
+var EVIDENCE_TAIL_RE = /\s*\(Evidence:?\s+([^)]+)\)\s*$/;
+var EVIDENCE_REF_RE = /L\d+/g;
+function parseRulesSection(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  let inRules = false;
+  const rules = [];
+  for (const line of lines) {
+    if (!inRules) {
+      if (RULE_HEADING_RE.test(line)) inRules = true;
+      continue;
+    }
+    if (NEXT_HEADING_RE.test(line)) break;
+    const m = RULE_LINE_RE.exec(line);
+    if (m === null) continue;
+    const ruleIndex = Number(m[1]);
+    let body = m[2];
+    const evidence = [];
+    let tail = EVIDENCE_TAIL_RE.exec(body);
+    while (tail !== null) {
+      const refs = tail[1];
+      const matches = refs.match(EVIDENCE_REF_RE);
+      if (matches !== null) evidence.unshift(...matches);
+      body = body.slice(0, tail.index).trimEnd();
+      tail = EVIDENCE_TAIL_RE.exec(body);
+    }
+    rules.push({ index: ruleIndex, body, evidence });
+  }
+  return rules;
+}
+var LEGACY_ARTIFACT_REL = [
+  "index.yaml",
+  "journal.md",
+  "journal.legacy.md",
+  "topics",
+  "distill-ledger.yaml",
+  "distill-proposal.md"
+];
+function deleteLegacyArtifacts(baseDir) {
+  const deleted = [];
+  for (const rel of LEGACY_ARTIFACT_REL) {
+    const abs = join(baseDir, rel);
+    if (!existsSync(abs)) continue;
+    rmSync(abs, { recursive: true, force: true });
+    deleted.push(abs);
+  }
+  return deleted;
+}
+
+// src/lessons/import-legacy-merge.ts
+async function mergeLegacy(projectRoot, paths, specs, summaryByTopic, options) {
+  let addedLessons = 0;
+  const addedTriggers = /* @__PURE__ */ new Set();
+  const touchedTopics = /* @__PURE__ */ new Set();
+  await mutateLessonsGraphLocked(projectRoot, (g) => {
+    addedLessons = 0;
+    addedTriggers.clear();
+    touchedTopics.clear();
+    for (const spec of specs) {
+      const result = addLessonInto(g, spec, {
+        allowNewTopic: true,
+        topicSummary: summaryByTopic.get(spec.topic),
+        // Legacy lessons may predate the ≥1-trigger requirement; recover them
+        // as-is rather than dropping historical knowledge.
+        allowNoTrigger: true
+      });
+      if (result.isNewLesson) addedLessons += 1;
+      for (const t of result.newTriggerIds) addedTriggers.add(t);
+      touchedTopics.add(spec.topic);
+    }
+  });
+  const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
+  return {
+    wroteGraphPath: paths.graph,
+    deletedPaths,
+    topicCount: touchedTopics.size,
+    lessonCount: addedLessons,
+    triggerCount: addedTriggers.size
+  };
+}
+var BASE_REL = ".agentsmesh/lessons";
+function lessonsPaths(projectRoot) {
+  const base = join(projectRoot, BASE_REL);
+  return {
+    base,
+    graph: join(base, "lessons.json"),
+    config: join(base, "config.json"),
+    journal: join(base, "journal.md"),
+    index: join(base, "index.yaml"),
+    topicsDir: join(base, "topics")
+  };
+}
+function toRelPath(projectRoot, absolute) {
+  return relative(projectRoot, absolute).split(sep).join("/");
+}
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
+
+**Recall \u2014 MUST run before every file edit and every state-changing command** (build/test/install/migrate/git-write): \`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule. Pure-read commands (cat/ls/grep/git-log) and the recall query itself are exempt.
+
+**Capture \u2014 MUST run immediately after any failure** (a failing test/CI/lint/typecheck, a code review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's): \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+No shell? Use the \`lessons_query\` / \`lessons_add\` MCP tools. Skip either and the system does not exist.`;
+
+// src/lessons/import-legacy.ts
+var LessonsGraphExistsError = class extends Error {
+  code = "LESSONS_GRAPH_EXISTS";
+  constructor() {
+    super("importLegacyLessons: a non-empty lessons.json already exists; pass force to overwrite.");
+    this.name = "LessonsGraphExistsError";
+  }
+};
+async function importLegacyLessons(projectRoot, options) {
+  const paths = lessonsPaths(projectRoot);
+  const indexRaw = readFileSync(paths.index, "utf8");
+  const index = LegacyIndexSchema.parse(parse(indexRaw));
+  const topics = {};
+  const triggersById = /* @__PURE__ */ new Map();
+  const triggerIdByKey = /* @__PURE__ */ new Map();
+  const lessons = {};
+  const specs = [];
+  const summaryByTopic = /* @__PURE__ */ new Map();
+  for (const cluster of index.clusters) {
+    topics[cluster.topic] = { summary: cluster.summary };
+    summaryByTopic.set(cluster.topic, cluster.summary);
+    const clusterTriggerIds = collectClusterTriggerIds(cluster, triggersById, triggerIdByKey);
+    const topicFile = join(projectRoot, cluster.file);
+    if (!existsSync(topicFile)) {
+      throw new Error(
+        `importLegacyLessons: declared topic file is missing: ${cluster.file}. Refusing to migrate (legacy artifacts left intact).`
+      );
+    }
+    const topicMarkdown = readFileSync(topicFile, "utf8");
+    for (const { index: ruleIndex, body, evidence } of parseRulesSection(topicMarkdown)) {
+      const lessonEvidence = [
+        `legacy:${cluster.file}#rule-${ruleIndex}`,
+        ...evidence.map((e) => `legacy:${e}`)
+      ];
+      lessons[`${cluster.topic}-rule-${ruleIndex}`] = {
+        rule: body,
+        topics: [cluster.topic],
+        triggers: clusterTriggerIds,
+        evidence: lessonEvidence,
+        status: "active",
+        createdAt: options.migratedAt
+      };
+      specs.push({
+        rule: body,
+        topic: cluster.topic,
+        triggers: {
+          files: cluster.triggers.file_globs,
+          commands: cluster.triggers.command_patterns,
+          keywords: cluster.triggers.keywords
+        },
+        evidence: lessonEvidence,
+        createdAt: options.migratedAt
+      });
+    }
+  }
+  if (options.merge === true)
+    return mergeLegacy(projectRoot, paths, specs, summaryByTopic, options);
+  const triggers = Object.fromEntries(triggersById.entries());
+  await mutateLessonsGraphLocked(projectRoot, (g) => {
+    const populated = Object.keys(g.lessons).length > 0 || Object.keys(g.topics).length > 0 || Object.keys(g.triggers).length > 0;
+    if (options.force !== true && populated) {
+      throw new LessonsGraphExistsError();
+    }
+    g.version = 1;
+    g.lessons = lessons;
+    g.topics = topics;
+    g.triggers = triggers;
+  });
+  const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
+  return {
+    wroteGraphPath: paths.graph,
+    deletedPaths,
+    topicCount: Object.keys(topics).length,
+    lessonCount: Object.keys(lessons).length,
+    triggerCount: triggersById.size
+  };
+}
+
+// src/lessons/auto-migrate.ts
+function todayIso2() {
+  const now = /* @__PURE__ */ new Date();
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+async function maybeAutoMigrateLessons(projectRoot) {
+  if (existsSync(graphFilePath(projectRoot))) return false;
+  const paths = lessonsPaths(projectRoot);
+  if (!existsSync(paths.index)) return false;
+  try {
+    await importLegacyLessons(projectRoot, { migratedAt: todayIso2() });
+    return true;
+  } catch (err) {
+    if (err instanceof LessonsGraphExistsError) return false;
+    throw err;
+  }
+}
+
+// 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/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 });
+    }
+    attempt++;
+    await sleep(delay);
+  }
+}
+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;
+  }
+}
+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;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+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((resolve6) => setTimeout(resolve6, ms));
+}
+
+// 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
+        });
+      }
+    }
+    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
+      });
+    }
+  }
+}
+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
+      });
+    }
+  }
+}
+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);
+  }
+  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
+      });
+    }
+    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
+      });
+    }
+  }
+}
+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;
+    }
+    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
+      });
+    }
+  }
+  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;
+    }
+  }
+}
+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
+      });
+    }
+  }
+}
+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/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;
+  }
+};
+function isNonLineTerminator(c) {
+  return c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
+}
+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 };
+    }
+  }
+}
+function compileNfa(ast) {
+  const b = new Builder();
+  const { start, end } = compileNode(b, ast);
+  return { states: b.states, start, accept: end };
+}
+
+// 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 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 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);
+    }
+  };
+}
+
+// src/lessons/regex-linear/ast.ts
+var UnsupportedRegexError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedRegexError";
+  }
+};
+
+// 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 });
+  }
+  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;
+  }
+}
+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 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 };
+}
+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 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;
+  }
+}
+
+// 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 };
+  }
+  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 };
+  }
+  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;
+  }
+  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 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`);
+    }
+    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;
+      }
+    }
+    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 };
+    }
+    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());
+    }
+    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();
+      }
+      const a = lo.codePointAt(0);
+      const b = hi.codePointAt(0);
+      return (c) => {
+        const p = c.codePointAt(0);
+        return p >= a && p <= b;
+      };
+    }
+    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;
+  }
+  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);
+}
+
+// src/lessons/validate-quality.ts
+function collectDuplicateRules(graph, findings) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    const key = normalizeRule2(lesson.rule);
+    const bucket = byKey.get(key) ?? [];
+    bucket.push(lessonId);
+    byKey.set(key, bucket);
+  }
+  for (const [key, ids] of byKey) {
+    if (ids.length < 2) continue;
+    const sorted = [...ids].sort();
+    for (const lessonId of sorted) {
+      const others = sorted.filter((other) => other !== lessonId);
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_RULE",
+        message: `Lesson "${lessonId}" duplicates rule text of: ${others.join(", ")} (normalized key: "${key.slice(0, 60)}").`,
+        lessonId
+      });
+    }
+  }
+}
+function collectInvalidTriggerPatterns(graph, findings) {
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    try {
+      new RegExp(trigger.pattern);
+    } catch (err) {
+      findings.push({
+        level: "error",
+        code: "INVALID_TRIGGER_PATTERN",
+        message: `Trigger "${triggerId}" has an invalid command_pattern regex (${trigger.pattern}): ${err instanceof Error ? err.message : String(err)}.`,
+        triggerId
+      });
+      continue;
+    }
+    if (!isSafeRegexPattern(trigger.pattern)) {
+      findings.push({
+        level: "error",
+        code: "UNSAFE_TRIGGER_PATTERN",
+        message: `Trigger "${triggerId}" has a command_pattern regex outside the provably-linear subset (${trigger.pattern}): it can backtrack catastrophically (e.g. a quantified group like (a+)+ or (a|aa)+, adjacent repetition like a+a+, or a backreference/lookaround). Rewrite using a linear pattern.`,
+        triggerId
+      });
+    }
+  }
+}
+function collectBackslashGlobPatterns(graph, findings) {
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!trigger.pattern.includes("\\")) continue;
+    findings.push({
+      level: "error",
+      code: "BACKSLASH_GLOB_PATTERN",
+      message: `Trigger "${triggerId}" has a file_glob pattern with a backslash (${trigger.pattern}); recall normalizes paths to forward slashes, so it never fires. Replace \\ with /.`,
+      triggerId
+    });
+  }
+}
+function collectDuplicateTriggers(graph, findings) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    const key = `${trigger.kind}|${trigger.pattern}`;
+    const bucket = byKey.get(key) ?? [];
+    bucket.push(triggerId);
+    byKey.set(key, bucket);
+  }
+  for (const [key, ids] of byKey) {
+    if (ids.length < 2) continue;
+    const sorted = [...ids].sort();
+    for (const triggerId of sorted) {
+      const others = sorted.filter((other) => other !== triggerId);
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TRIGGER",
+        message: `Trigger "${triggerId}" duplicates (kind, pattern) of: ${others.join(", ")} (key: "${key}").`,
+        triggerId
+      });
+    }
+  }
+}
+var HIGH_FANOUT_THRESHOLD = 10;
+function collectFanout(graph, findings) {
+  const fanout = /* @__PURE__ */ new Map();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) fanout.set(t, (fanout.get(t) ?? 0) + 1);
+  }
+  let over = 0;
+  let max = 0;
+  for (const n of fanout.values()) {
+    if (n > HIGH_FANOUT_THRESHOLD) over += 1;
+    if (n > max) max = n;
+  }
+  if (over > 0) {
+    findings.push({
+      level: "warning",
+      code: "HIGH_FANOUT_TRIGGERS",
+      message: `${over} trigger(s) each match more than ${HIGH_FANOUT_THRESHOLD} active lessons (max ${max}); recall returns the ranked top by default \u2014 consider per-lesson trigger refinement to improve precision.`
+    });
+  }
+}
+function collectLowSignalKeywords(graph, findings) {
+  const activeTriggerIds2 = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) activeTriggerIds2.add(t);
+  }
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "keyword") continue;
+    if (!activeTriggerIds2.has(triggerId)) continue;
+    if (!isLowSignalKeyword(trigger.pattern)) continue;
+    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.`,
+      triggerId
+    });
+  }
+}
+function collectStopwordKeywords(graph, findings) {
+  const activeTriggerIds2 = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) activeTriggerIds2.add(t);
+  }
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "keyword") continue;
+    if (!activeTriggerIds2.has(triggerId)) continue;
+    if (tokenize(trigger.pattern).length !== 0 && !keywordNeedleLosesTokens(trigger.pattern)) {
+      continue;
+    }
+    findings.push({
+      level: "warning",
+      code: "STOPWORD_KEYWORD",
+      message: `Keyword trigger "${triggerId}" (${trigger.pattern}) loses tokens to stopword filtering, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art"), or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
+function normalizeRule2(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+// src/lessons/validate.ts
+function validateLessonsGraph(graph, options = {}) {
+  const findings = [];
+  const schemaResult = LessonsGraphSchema.safeParse(graph);
+  if (!schemaResult.success) {
+    findings.push({
+      level: "error",
+      code: "SCHEMA_INVALID",
+      message: schemaResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    });
+    return { ok: false, findings };
+  }
+  collectDanglingRefs(graph, findings);
+  collectDuplicateRefs(graph, findings);
+  collectStatusInvariants(graph, findings);
+  collectLifecycleInvariants(graph, findings);
+  collectDuplicateRules(graph, findings);
+  collectReachability(graph, findings);
+  collectInvalidTriggerPatterns(graph, findings);
+  collectBackslashGlobPatterns(graph, findings);
+  collectDuplicateTriggers(graph, findings);
+  collectOrphans(graph, findings);
+  collectFanout(graph, findings);
+  collectLowSignalKeywords(graph, findings);
+  collectStopwordKeywords(graph, findings);
+  collectRunnerAnchoredPatterns(graph, findings);
+  if (options.knownPaths !== void 0) collectDeadFileGlobs(graph, findings, options.knownPaths);
+  const ok = findings.every((f) => f.level !== "error");
+  return { ok, findings };
+}
+
+// src/lessons/mutate.ts
+function emptyGraph() {
+  return { version: 1, lessons: {}, topics: {}, triggers: {} };
+}
+async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
+  const release = await acquireLessonsLock(projectRoot, { retries: options.retries });
+  try {
+    const graph = tryLoadLessonsGraph(projectRoot) ?? emptyGraph();
+    const result = await mutator(graph);
+    const report = validateLessonsGraph(graph);
+    if (!report.ok) {
+      const errors = report.findings.filter((f) => f.level === "error").map((f) => `${f.code}: ${f.message}`).join("; ");
+      throw new Error(`mutateLessonsGraph: refusing to write an invalid graph \u2014 ${errors}`);
+    }
+    saveLessonsGraph(projectRoot, graph);
+    return result;
+  } finally {
+    await release();
+  }
+}
+async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
+  await maybeAutoMigrateLessons(projectRoot);
+  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
+  });
+}
+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 existingId = findExistingLessonByRule(graph, ruleKey);
+  const isNewTopic = graph.topics[input.topic] === void 0;
+  if (isNewTopic) {
+    if (options.allowNewTopic !== true) throw new UnknownTopicError(input.topic);
+    if (options.topicSummary === void 0 || options.topicSummary.length === 0) {
+      throw new Error(`addLesson: new topic "${input.topic}" requires topicSummary.`);
+    }
+    graph.topics[input.topic] = { summary: options.topicSummary };
+  }
+  if (options.allowNoTrigger !== true) {
+    const existingTriggers = existingId !== null ? graph.lessons[existingId]?.triggers.length ?? 0 : 0;
+    if (countInputTriggers(input.triggers) === 0 && existingTriggers === 0) {
+      throw new NoTriggerError();
+    }
+  }
+  const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
+  if (options.allowNoTrigger !== true) {
+    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 (existingId !== null) {
+    const existing = 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 } : {}
+    };
+    return {
+      id: existingId,
+      isNewLesson: false,
+      isNewTopic,
+      newTriggerIds,
+      // Near-duplicate detection is meaningless on an upsert (the lesson IS the
+      // match), so only DEAD_GLOB/hygiene warnings apply here.
+      warnings: inspectCapturedLesson(graph, existingId, options.knownPaths)
+    };
+  }
+  const id = makeLessonId(graph, input.topic, ruleKey);
+  graph.lessons[id] = {
+    rule: trimmedRule,
+    topics: [input.topic],
+    triggers: triggerIds,
+    evidence: input.evidence === void 0 ? [] : [...input.evidence],
+    status: "active",
+    createdAt: input.createdAt ?? todayIso(),
+    ...input.rationale === void 0 ? {} : { rationale: input.rationale }
+  };
+  const warnings = inspectCapturedLesson(graph, id, options.knownPaths);
+  const nearDup = nearDuplicateWarning(graph, id);
+  return {
+    id,
+    isNewLesson: true,
+    isNewTopic,
+    newTriggerIds,
+    warnings: nearDup === null ? warnings : [...warnings, nearDup]
+  };
+}
+function findExistingLessonByRule(graph, ruleKey) {
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (normalizeRule(lesson.rule) === ruleKey) return id;
+  }
+  return null;
+}
+
+// src/lessons/ranking-signals.ts
+function buildFanout(graph) {
+  const fanout = /* @__PURE__ */ new Map();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) fanout.set(t, (fanout.get(t) ?? 0) + 1);
+  }
+  return fanout;
+}
+function buildTopicCoherence(matches) {
+  const topicCount = /* @__PURE__ */ new Map();
+  for (const { lesson } of matches) {
+    for (const t of lesson.topics) topicCount.set(t, (topicCount.get(t) ?? 0) + 1);
+  }
+  const coherence = /* @__PURE__ */ new Map();
+  for (const { id, lesson } of matches) {
+    let best = 0;
+    for (const t of lesson.topics) best = Math.max(best, topicCount.get(t));
+    coherence.set(id, best);
+  }
+  return coherence;
+}
+
+// src/lessons/prune.ts
+function planPrune(graph, options = {}) {
+  const cap = Math.max(1, options.cap ?? MAX_RECOMMENDED_TRIGGERS);
+  const fanout = buildFanout(graph);
+  const trimmedLessons = [];
+  const keptByLesson = /* @__PURE__ */ new Map();
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (options.trimOverCap === false || lesson.triggers.length <= cap) {
+      keptByLesson.set(id, lesson.triggers);
+      continue;
+    }
+    const ordered = [...lesson.triggers].sort((a, b) => {
+      const fa = fanout.get(a);
+      const fb = fanout.get(b);
+      return fa !== fb ? fa - fb : a < b ? -1 : 1;
+    });
+    const drop = new Set(ordered.slice(cap));
+    const kept = lesson.triggers.filter((t) => !drop.has(t));
+    keptByLesson.set(id, kept);
+    trimmedLessons.push({ id, removedTriggers: [...drop], keptCount: kept.length });
+  }
+  const removedDeadGlobs = [];
+  const unreachableLessons = [];
+  if (options.knownPaths !== void 0) {
+    const dead = deadFileGlobIds(graph, options.knownPaths);
+    if (dead.size > 0) {
+      for (const [id, kept] of keptByLesson) {
+        const deadInLesson = kept.filter((t) => dead.has(t));
+        if (deadInLesson.length === 0) continue;
+        const remaining = kept.filter((t) => !dead.has(t));
+        if (remaining.length >= 1) {
+          keptByLesson.set(id, remaining);
+          removedDeadGlobs.push({ id, removedTriggers: deadInLesson, keptCount: remaining.length });
+        } else {
+          unreachableLessons.push(id);
+        }
+      }
+      unreachableLessons.sort();
+    }
+  }
+  const live = /* @__PURE__ */ new Set();
+  for (const kept of keptByLesson.values()) for (const t of kept) live.add(t);
+  const removedTriggerIds = Object.keys(graph.triggers).filter((t) => !live.has(t)).sort();
+  const referencedTopics = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    for (const topic of lesson.topics) referencedTopics.add(topic);
+  }
+  const removedTopicIds = Object.keys(graph.topics).filter((t) => !referencedTopics.has(t)).sort();
+  return { removedTriggerIds, removedTopicIds, trimmedLessons, removedDeadGlobs, unreachableLessons, cap };
+}
+function applyPruneToGraph(graph, plan) {
+  for (const trim of [...plan.trimmedLessons, ...plan.removedDeadGlobs ?? []]) {
+    const lesson = graph.lessons[trim.id];
+    if (lesson === void 0) continue;
+    const drop = new Set(trim.removedTriggers);
+    graph.lessons[trim.id] = { ...lesson, triggers: lesson.triggers.filter((t) => !drop.has(t)) };
+  }
+  for (const topicId of plan.removedTopicIds) delete graph.topics[topicId];
+  const dead = new Set(plan.removedTriggerIds);
+  if (dead.size === 0) return;
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.triggers.some((t) => dead.has(t))) {
+      graph.lessons[id] = { ...lesson, triggers: lesson.triggers.filter((t) => !dead.has(t)) };
+    }
+  }
+  for (const t of dead) delete graph.triggers[t];
+}
+function isEmptyPrunePlan(plan) {
+  return plan.removedTriggerIds.length === 0 && plan.removedTopicIds.length === 0 && plan.trimmedLessons.length === 0 && plan.removedDeadGlobs.length === 0;
+}
+
+// src/lessons/auto-prune.ts
+function isAutoPruneEnabled(projectRoot) {
+  const path = lessonsPaths(projectRoot).config;
+  if (!existsSync(path)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return false;
+    return parsed.autoPrune === true;
+  } catch {
+    return false;
+  }
+}
+async function maybeAutoPrune(projectRoot, knownPaths) {
+  if (!isAutoPruneEnabled(projectRoot)) return null;
+  const preview = tryLoadLessonsGraph(projectRoot);
+  if (preview === null) return null;
+  if (isEmptyPrunePlan(planPrune(preview, { trimOverCap: false, knownPaths }))) return null;
+  let summary = { removedTriggers: 0, removedTopics: 0, detachedDeadGlobs: 0 };
+  await mutateLessonsGraph(projectRoot, (graph) => {
+    const plan = planPrune(graph, { trimOverCap: false, knownPaths });
+    if (isEmptyPrunePlan(plan)) return;
+    applyPruneToGraph(graph, plan);
+    summary = {
+      removedTriggers: plan.removedTriggerIds.length,
+      removedTopics: plan.removedTopicIds.length,
+      detachedDeadGlobs: plan.removedDeadGlobs.reduce((n, t) => n + t.removedTriggers.length, 0)
+    };
+  });
+  const total = summary.removedTriggers + summary.removedTopics + summary.detachedDeadGlobs;
+  return total > 0 ? summary : null;
+}
+function appendJsonl(path, record, opts) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}
+`, "utf8");
+  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
+}
+function capJsonl(path, maxRecords) {
+  if (!existsSync(path)) return;
+  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length <= maxRecords) return;
+  const kept = lines.slice(lines.length - maxRecords);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${kept.join("\n")}
+`, "utf8");
+  renameSync(tmp, path);
+}
+var MAX_RECALL_LOG_RECORDS = 5e3;
+var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
+var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
+var SESSION_ENV = "AGENTSMESH_SESSION_ID";
+function sessionId(env = process.env) {
+  const raw = env[SESSION_ENV];
+  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
+}
+function recallLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+}
+function isTelemetryEnabled(env = process.env) {
+  return env[TELEMETRY_ENV] === "1";
+}
+function appendRecallRecord(projectRoot, record, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  appendJsonl(recallLogPath(projectRoot), record, {
+    maxRecords: MAX_RECALL_LOG_RECORDS,
+    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+
+// src/lessons/capture-telemetry.ts
+var MAX_CAPTURE_LOG_RECORDS = 5e3;
+var CAPTURE_LOG_TRIM_TRIGGER_BYTES = 2e6;
+function captureLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
+}
+function appendCaptureRecord(projectRoot, record, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  appendJsonl(captureLogPath(projectRoot), record, {
+    maxRecords: MAX_CAPTURE_LOG_RECORDS,
+    trimTriggerBytes: CAPTURE_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+function recordCapture(projectRoot, triggerKinds, result, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  const session = sessionId(env);
+  appendCaptureRecord(
+    projectRoot,
+    {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      isNewLesson: result?.isNewLesson ?? false,
+      isNewTopic: result?.isNewTopic ?? false,
+      newTriggerCount: result?.newTriggerIds.length ?? 0,
+      triggerKinds,
+      blocked: result === null,
+      warningCodes: result?.warnings.map((w) => w.code) ?? [],
+      ...session !== void 0 ? { session } : {},
+      ...result !== null ? { lessonId: result.id } : {}
+    },
+    env
+  );
+}
+function normalizeRecallFile(file, projectRoot) {
+  const forward = file.replaceAll("\\", "/");
+  const direct = relativize(projectRoot, forward);
+  if (!direct.startsWith("../")) return direct;
+  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
+  return viaReal.startsWith("../") ? direct : viaReal;
+}
+function relativize(root, forward) {
+  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
+  return rel === "" ? forward.replaceAll("\\", "/") : rel;
+}
+function safeRealpath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    if (parent === path) return path;
+    return resolve(safeRealpath(parent), basename(path));
+  }
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
+var MAX_FILES = 2e5;
+function listProjectFiles(projectRoot) {
+  const out = /* @__PURE__ */ new Set();
+  try {
+    const stack = [projectRoot];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          if (!SKIP_DIRS.has(entry.name)) stack.push(join(dir, entry.name));
+        } else if (entry.isFile()) {
+          out.add(toRelPath(projectRoot, join(dir, entry.name)));
+          if (out.size > MAX_FILES) return out;
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return out;
+}
+
+// src/lessons/keyword-match.ts
+function splitTokens(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function deriveHaystackTokens(query) {
+  const parts = [];
+  if (query.file !== void 0) parts.push(query.file);
+  if (query.command !== void 0) parts.push(query.command);
+  return parts.length === 0 ? [] : splitTokens(parts.join(" "));
+}
+function containsRun(needle, hay) {
+  if (needle.length === 0) return false;
+  for (let i = 0; i + needle.length <= hay.length; i += 1) {
+    let hit = true;
+    for (let j = 0; j < needle.length; j += 1) {
+      if (hay[i + j] !== needle[j]) {
+        hit = false;
+        break;
+      }
+    }
+    if (hit) return true;
+  }
+  return false;
+}
+function keywordMatches(pattern, query) {
+  if (query.keyword !== void 0 && query.keyword.toLowerCase().includes(pattern.toLowerCase())) {
+    return true;
+  }
+  return containsRun(tokenize(pattern), deriveHaystackTokens(query));
+}
+
+// src/lessons/query.ts
+var COMMAND_MATCH_BUDGET = 5e6;
+function queryLessons(graph, query) {
+  if (query.file === void 0 && query.command === void 0 && query.keyword === void 0) {
+    return [];
+  }
+  const matchedTriggerIds = collectMatchedTriggerIds(graph, query);
+  const matched = [];
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (lesson.triggers.some((t) => matchedTriggerIds.has(t))) {
+      matched.push({ id, lesson });
+    }
+  }
+  matched.sort((a, b) => a.id < b.id ? -1 : 1);
+  return matched;
+}
+function collectMatchedTriggersByKind(graph, query) {
+  const byKind = {
+    file_glob: /* @__PURE__ */ new Set(),
+    command_pattern: /* @__PURE__ */ new Set(),
+    keyword: /* @__PURE__ */ new Set()
+  };
+  const budget = { remaining: COMMAND_MATCH_BUDGET };
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    if (triggerMatches(trigger, query, budget)) byKind[trigger.kind].add(id);
+  }
+  return byKind;
+}
+function collectMatchedTriggerIds(graph, query) {
+  const { file_glob, command_pattern, keyword } = collectMatchedTriggersByKind(graph, query);
+  return /* @__PURE__ */ new Set([...file_glob, ...command_pattern, ...keyword]);
+}
+function triggerMatches(trigger, query, budget) {
+  switch (trigger.kind) {
+    case "file_glob":
+      if (query.file === void 0) return false;
+      return picomatch(trigger.pattern, { dot: true })(query.file);
+    case "command_pattern": {
+      if (query.command === void 0) return false;
+      const matcher = getCommandMatcher(trigger.pattern);
+      return matcher !== null && matcher.test(query.command, budget);
+    }
+    case "keyword":
+      return keywordMatches(trigger.pattern, query);
+  }
+}
+
+// src/lessons/ranking.ts
+var DEFAULT_RECALL_LIMIT = 10;
+var DEFAULT_RECALL_MAX_TOKENS = 400;
+var RRF_K = 60;
+var SPECIFICITY_WEIGHT = 3;
+var TOPIC_COHERENCE_WEIGHT = 2;
+var BM25_WEIGHT = 1;
+function rankMap(items) {
+  const sorted = [...items].sort(
+    (a, b) => b.value !== a.value ? b.value - a.value : a.id < b.id ? -1 : 1
+  );
+  const ranks = /* @__PURE__ */ new Map();
+  let prevValue = null;
+  let prevRank = 0;
+  sorted.forEach((item, i) => {
+    const rank = prevValue !== null && item.value === prevValue ? prevRank : i + 1;
+    ranks.set(item.id, rank);
+    prevValue = item.value;
+    prevRank = rank;
+  });
+  return ranks;
+}
+function estTokens(rule) {
+  return Math.ceil(rule.length / 4);
+}
+function rankLessons(graph, query, matches, options = {}) {
+  if (matches.length === 0) return [];
+  const terms = queryTerms(query);
+  const corpus = buildCorpus(graph);
+  const fanout = buildFanout(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));
+    return {
+      id,
+      lesson,
+      bm25: bm25(terms, lesson.rule, corpus),
+      specificity,
+      // `id` is a matched lesson, and buildTopicCoherence keys every matched id.
+      topicCoherence: coherence.get(id),
+      matchedTriggers: hitTriggers
+    };
+  });
+  const bm25Ranks = rankMap(scored.map((s) => ({ id: s.id, value: s.bm25 })));
+  const specRanks = rankMap(scored.map((s) => ({ id: s.id, value: s.specificity })));
+  const topicRanks = rankMap(scored.map((s) => ({ id: s.id, value: s.topicCoherence })));
+  const ranked = scored.map((s) => ({
+    id: s.id,
+    lesson: s.lesson,
+    score: SPECIFICITY_WEIGHT / (RRF_K + specRanks.get(s.id)) + TOPIC_COHERENCE_WEIGHT / (RRF_K + topicRanks.get(s.id)) + BM25_WEIGHT / (RRF_K + bm25Ranks.get(s.id)),
+    reason: {
+      matchedTriggers: s.matchedTriggers,
+      bm25: s.bm25,
+      specificity: s.specificity,
+      topicCoherence: s.topicCoherence
+    }
+  })).sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const ca = a.lesson.createdAt;
+    const cb = b.lesson.createdAt;
+    if (ca !== cb) return ca < cb ? 1 : -1;
+    return a.id < b.id ? -1 : 1;
+  });
+  return applyCaps(ranked, options);
+}
+function applyCaps(ranked, options) {
+  let out = ranked;
+  if (options.limit !== void 0 && options.limit >= 0) out = out.slice(0, options.limit);
+  if (options.maxTokens !== void 0 && out.length > 0) {
+    const budgeted = [out[0]];
+    let used = estTokens(out[0].lesson.rule);
+    for (const row of out.slice(1)) {
+      const cost = estTokens(row.lesson.rule);
+      if (used + cost > options.maxTokens) break;
+      used += cost;
+      budgeted.push(row);
+    }
+    out = budgeted;
+  }
+  return out;
+}
+function defaultLessonsConfig() {
+  return {
+    recallLimit: DEFAULT_RECALL_LIMIT,
+    recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
+    autoPrune: false
+  };
+}
+function positiveInt(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+function loadRecallConfig(projectRoot) {
+  const fallback = {
+    limit: DEFAULT_RECALL_LIMIT,
+    maxTokens: DEFAULT_RECALL_MAX_TOKENS
+  };
+  const path = lessonsPaths(projectRoot).config;
+  if (!existsSync(path)) return fallback;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return fallback;
+    const cfg = parsed;
+    return {
+      limit: positiveInt(cfg.recallLimit) ?? fallback.limit,
+      maxTokens: positiveInt(cfg.recallMaxTokens) ?? fallback.maxTokens
+    };
+  } catch {
+    return fallback;
+  }
+}
+var SEEN_DIR = "agentsmesh-lessons-seen";
+function openSessionDedup(options = {}) {
+  if (options.disabled === true) return null;
+  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
+  if (id === void 0) return null;
+  const path = seenPath(id);
+  return { sessionId: id, seen: loadSeen(path), path };
+}
+function seenPath(id) {
+  const safe = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 200);
+  return join(tmpdir(), SEEN_DIR, `${safe}.json`);
+}
+function loadSeen(path) {
+  if (!existsSync(path)) return /* @__PURE__ */ new Set();
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
+    return new Set(parsed.filter((x) => typeof x === "string"));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function filterUnseen(dedup, matches) {
+  return matches.filter((m) => !dedup.seen.has(m.id));
+}
+function commitSeen(dedup, returnedIds) {
+  if (returnedIds.length === 0) return;
+  const union3 = new Set(dedup.seen);
+  for (const id of returnedIds) union3.add(id);
+  if (union3.size === dedup.seen.size) return;
+  try {
+    mkdirSync(dirname(dedup.path), { recursive: true });
+    const tmp = `${dedup.path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify([...union3]), "utf8");
+    renameSync(tmp, dedup.path);
+  } catch {
+  }
+}
+
+// src/lessons/recall.ts
+async function recallLessons(projectRoot, query, options = {}) {
+  try {
+    await maybeAutoMigrateLessons(projectRoot);
+  } catch {
+  }
+  const load = loadLessonsGraphResilient(projectRoot);
+  if (load.status === "corrupt") {
+    return { lessons: [], totalMatches: 0, suppressed: 0, corrupt: true };
+  }
+  if (load.status === "newer-version") {
+    return { lessons: [], totalMatches: 0, suppressed: 0, newerVersion: load.version };
+  }
+  if (load.status === "absent") return { lessons: [], totalMatches: 0, suppressed: 0 };
+  const graph = load.graph;
+  const matchQuery = query.file === void 0 ? query : { ...query, file: normalizeRecallFile(query.file, projectRoot) };
+  const matches = queryLessons(graph, matchQuery);
+  const dedup = openSessionDedup({ explicit: options.sessionId, disabled: options.noDedup });
+  const forRank = dedup === null ? matches : filterUnseen(dedup, matches);
+  const cfg = loadRecallConfig(projectRoot);
+  const lessons = rankLessons(graph, matchQuery, forRank, {
+    limit: options.limit ?? cfg.limit,
+    maxTokens: options.maxTokens === null ? void 0 : options.maxTokens ?? cfg.maxTokens
+  });
+  if (dedup !== null) commitSeen(dedup, lessons.map((l) => l.id));
+  recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, { bypassed: false });
+  return { lessons, totalMatches: matches.length, suppressed: matches.length - forRank.length };
+}
+function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, options = {}) {
+  if (!isTelemetryEnabled()) return;
+  const byKind = collectMatchedTriggersByKind(graph, query);
+  const countVia = (set) => matches.filter(({ lesson }) => lesson.triggers.some((t) => set.has(t))).length;
+  const session = sessionId();
+  appendRecallRecord(projectRoot, {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    hasFile: query.file !== void 0,
+    hasCommand: query.command !== void 0,
+    hasKeyword: query.keyword !== void 0,
+    totalMatches: matches.length,
+    returnedCount: lessons.length,
+    returnedTokens: lessons.reduce((sum, l) => sum + estTokens(l.lesson.rule), 0),
+    truncated: matches.length > lessons.length,
+    matchedByKind: {
+      file: countVia(byKind.file_glob),
+      command: countVia(byKind.command_pattern),
+      keyword: countVia(byKind.keyword)
+    },
+    lessonIds: lessons.map((l) => l.id),
+    bypassed: options.bypassed === true,
+    ...session !== void 0 ? { session } : {}
+  });
+}
+async function captureLesson(projectRoot, input, options = {}) {
+  await maybeAutoMigrateLessons(projectRoot);
+  const triggerKinds = {
+    file: input.triggers.files?.length ?? 0,
+    command: input.triggers.commands?.length ?? 0,
+    keyword: input.triggers.keywords?.length ?? 0
+  };
+  const knownPaths = options.knownPaths ?? listProjectFiles(projectRoot) ?? void 0;
+  try {
+    const result = await addLesson(projectRoot, input, { ...options, knownPaths });
+    recordCapture(projectRoot, triggerKinds, result);
+    const autoPruned = await maybeAutoPrune(projectRoot, knownPaths);
+    return autoPruned === null ? result : { ...result, autoPruned };
+  } catch (err) {
+    recordCapture(projectRoot, triggerKinds, null);
+    throw err;
+  }
+}
+
+// src/lessons/merge.ts
+async function mergeLessons(projectRoot, loserId, keeperId, options = {}) {
+  return mutateLessonsGraph(projectRoot, (graph) => mergeInto(graph, loserId, keeperId), {
+    retries: options.retries
+  });
+}
+function mergeInto(graph, loserId, keeperId) {
+  if (loserId === keeperId) {
+    throw new Error(`mergeLessons: cannot merge lesson "${loserId}" into itself.`);
+  }
+  const loser = graph.lessons[loserId];
+  if (loser === void 0) throw new Error(`mergeLessons: unknown lesson "${loserId}".`);
+  const keeper = graph.lessons[keeperId];
+  if (keeper === void 0) throw new Error(`mergeLessons: unknown lesson "${keeperId}".`);
+  if (keeper.status !== "active") {
+    throw new Error(`mergeLessons: keeper "${keeperId}" is not active (status: ${keeper.status}).`);
+  }
+  if (loser.status !== "active") {
+    throw new Error(
+      `mergeLessons: loser "${loserId}" is already ${loser.status}; nothing to merge.`
+    );
+  }
+  graph.lessons[keeperId] = {
+    ...keeper,
+    triggers: union2(keeper.triggers, loser.triggers),
+    topics: union2(keeper.topics, loser.topics),
+    evidence: union2(keeper.evidence, loser.evidence)
+  };
+  graph.lessons[loserId] = { ...loser, status: "superseded", supersededBy: keeperId };
+  return { loserId, keeperId };
+}
+function union2(base, extra) {
+  const out = [...base];
+  for (const item of extra) {
+    if (!out.includes(item)) out.push(item);
+  }
+  return out;
+}
+
+// src/lessons/strip-markers.ts
+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"),
+  // " (L174)" / " (L92, L163)"
+  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]\.?`, "g")
+  // " [L161, L208]"
+];
+var ALSO_RELEVANT_PATTERN = /\s*\(also relevant[^)]*\)\s*/g;
+function stripLegacyMarkers(rule) {
+  let out = rule;
+  for (const pattern of LINE_REF_PATTERNS) out = out.replace(pattern, "");
+  out = out.replace(ALSO_RELEVANT_PATTERN, " ");
+  return out.trim();
+}
+function applyStrip(graph) {
+  const changedIds = [];
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    const stripped = stripLegacyMarkers(lesson.rule);
+    if (stripped === lesson.rule || stripped.length === 0) continue;
+    changedIds.push(id);
+    graph.lessons[id] = { ...lesson, rule: stripped };
+  }
+  return changedIds.sort();
+}
+async function stripMarkersInGraph(projectRoot, options = {}) {
+  await maybeAutoMigrateLessons(projectRoot);
+  const existing = tryLoadLessonsGraph(projectRoot);
+  if (existing === null) return { changedIds: [], changedCount: 0 };
+  if (options.dryRun === true) {
+    const changedIds2 = applyStrip(existing);
+    return { changedIds: changedIds2, changedCount: changedIds2.length };
+  }
+  let changedIds = [];
+  await mutateLessonsGraph(projectRoot, (graph) => {
+    changedIds = applyStrip(graph);
+  });
+  return { changedIds, changedCount: changedIds.length };
+}
+var RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
+var RECALL_HOOK_MATCHER = "Edit|Write|Bash";
+function injectRecallHook(projectRoot) {
+  const path = join(projectRoot, ".agentsmesh", "hooks.yaml");
+  if (!existsSync(path)) return false;
+  const doc = parseDocument(readFileSync(path, "utf8"));
+  const existing = doc.get("PostToolUse");
+  const post = existing instanceof YAMLSeq ? existing : new YAMLSeq();
+  const present = post.items.some(
+    (item) => item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND
+  );
+  if (present) return false;
+  post.add(
+    doc.createNode({ matcher: RECALL_HOOK_MATCHER, type: "command", command: RECALL_HOOK_COMMAND })
+  );
+  doc.set("PostToolUse", post);
+  writeFileSync(path, String(doc), "utf8");
+  return true;
+}
+var UTF8_BOM = "\uFEFF";
+var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".md",
+  ".mdc",
+  ".mdx",
+  ".markdown",
+  ".txt",
+  ".json",
+  ".jsonc",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ps1",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".tsx",
+  ".html",
+  ".css"
+]);
+var TEXT_DOTFILES = /* @__PURE__ */ new Set([
+  ".gitignore",
+  ".cursorignore",
+  ".cursorindexingignore",
+  ".aiignore",
+  ".agentignore",
+  ".clineignore",
+  ".geminiignore",
+  ".codeiumignore",
+  ".continueignore",
+  ".copilotignore",
+  ".windsurfignore",
+  ".junieignore",
+  ".kiroignore",
+  ".rooignore",
+  ".antigravityignore"
+]);
+function shouldNormalizeLineEndings(path) {
+  const ext = extname(path).toLowerCase();
+  if (ext.length > 0) return TEXT_EXTENSIONS.has(ext);
+  const base = basename(path).toLowerCase();
+  return TEXT_DOTFILES.has(base);
+}
+function normalizeLineEndings(content) {
+  return content.replace(/\r\n?/g, "\n");
+}
+var EXECUTABLE_SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".sh", ".bash", ".zsh"]);
+function executableModeFor(path) {
+  return EXECUTABLE_SCRIPT_EXTENSIONS.has(extname(path).toLowerCase()) ? 493 : void 0;
+}
+
+// src/utils/filesystem/fs.ts
+async function readFileSafe(path) {
+  try {
+    const data = await readFile(path, "utf-8");
+    return data.startsWith(UTF8_BOM) ? data.slice(UTF8_BOM.length) : data;
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") return null;
+    throw new FileSystemError(
+      path,
+      `Failed to read ${path}: ${e.message}. Ensure the file exists and is readable.`,
+      { cause: err, errnoCode: e.code }
+    );
+  }
+}
+async function writeFileAtomic(path, content, options) {
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true });
+  try {
+    const info = await lstat(path);
+    if (info.isDirectory()) {
+      throw new FileSystemError(
+        path,
+        `Failed to write ${path}: target exists and is a directory. Remove it or choose a different path.`,
+        { errnoCode: "EISDIR" }
+      );
+    }
+    if (info.isSymbolicLink()) {
+      await unlink(path).catch((e) => {
+        if (e.code !== "ENOENT") throw e;
+      });
+    }
+  } catch (err) {
+    if (err instanceof FileSystemError) throw err;
+    const e = err;
+    if (e.code !== "ENOENT") throw err;
+  }
+  const tmpPath = `${path}.tmp`;
+  const payload = shouldNormalizeLineEndings(path) ? normalizeLineEndings(content) : content;
+  const mode = executableModeFor(path);
+  try {
+    try {
+      const tmpInfo = await lstat(tmpPath);
+      if (tmpInfo.isSymbolicLink()) {
+        await unlink(tmpPath);
+      }
+    } catch (tmpErr) {
+      if (tmpErr.code !== "ENOENT") throw tmpErr;
+    }
+    const writeOpts = {
+      encoding: "utf-8",
+      flag: "w"
+    };
+    if (mode !== void 0) writeOpts.mode = mode;
+    await writeFile(tmpPath, payload, writeOpts);
+    await rename(tmpPath, path);
+    if (mode !== void 0) {
+      await chmod(path, mode);
+    }
+  } catch (err) {
+    await rm(tmpPath, { force: true }).catch(() => {
+    });
+    const e = err;
+    throw new FileSystemError(
+      path,
+      `Failed to write ${path}: ${e.message}. Check permissions and disk space.`,
+      { cause: err, errnoCode: e.code }
+    );
+  }
+}
+
+// src/utils/filesystem/gitignore.ts
+async function ensureGitignoreEntries(projectRoot, entries) {
+  const gitignorePath = join(projectRoot, ".gitignore");
+  const current = await readFileSafe(gitignorePath) ?? "";
+  const existing = new Set(
+    current.split("\n").map((s) => s.trim()).filter((s) => s.length > 0 && !s.startsWith("#"))
+  );
+  const toAdd = entries.filter((e) => !isCoveredByExisting(e, existing));
+  if (toAdd.length === 0) return false;
+  const suffix = current.endsWith("\n") || current === "" ? "" : "\n";
+  await writeFileAtomic(gitignorePath, current + suffix + toAdd.join("\n") + "\n");
+  return true;
+}
+function isCoveredByExisting(candidate, existing) {
+  if (existing.has(candidate)) return true;
+  let parent = candidate.replace(/\/$/, "");
+  while (parent.includes("/")) {
+    parent = parent.slice(0, parent.lastIndexOf("/"));
+    if (parent === "") break;
+    if (existing.has(parent) || existing.has(`${parent}/`) || existing.has(`${parent}/**`)) {
+      return true;
+    }
+  }
+  return false;
+}
+var LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
+var LESSONS_CONTRACT_END = "<!-- agentsmesh:lessons-contract:end -->";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function managedBlockPattern(start, end) {
+  return new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, "g");
+}
+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() };
+}
+function insertAtBodyTop(content, block) {
+  const { prefix, body } = splitFrontmatterPrefix(content);
+  const placed = body ? `${block}
+
+${body}` : block;
+  return prefix ? `${prefix}
+
+${placed}` : placed;
+}
+
+// src/targets/projection/lessons-paragraph.ts
+var LESSONS_PARAGRAPH_BLOCK = `${LESSONS_CONTRACT_START}
+${LESSONS_PROCEDURAL_RULE}
+${LESSONS_CONTRACT_END}`;
+function appendLessonsParagraph(content) {
+  const withoutPrior = stripLessonsParagraph(content);
+  return insertAtBodyTop(withoutPrior, LESSONS_PARAGRAPH_BLOCK);
+}
+function stripLessonsParagraph(content) {
+  const withoutBlock = stripManagedBlock(content, LESSONS_CONTRACT_START, LESSONS_CONTRACT_END);
+  return stripRawProceduralRule(withoutBlock).trim();
+}
+function stripRawProceduralRule(content) {
+  return content.replace(`
+
+${LESSONS_PROCEDURAL_RULE}`, "").replace(LESSONS_PROCEDURAL_RULE, "");
+}
+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";
+var LESSONS_SKILL_DESCRIPTION = "Full operating manual for the agentsmesh lessons system (recall + capture). Consult when running any `agentsmesh lessons` subcommand (query, add, topics, show, deprecate, merge, untrigger, strip-markers, journal, validate, stats, prune, import-md), choosing a topic or trigger flags, using the lessons MCP tools, or when unsure how to phrase or capture a lesson.";
+var LESSONS_SKILL_BODY = `# Lessons \u2014 operating manual
+
+Two commands: **Recall** before you act, **Capture** after any failure. The graph
+\`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit.
+
+## Recall \u2014 before each file edit and each state-changing command
+
+\`agentsmesh lessons query --file <path> --cmd <command>\` (add \`--keyword <text>\` to
+match by task), then apply every rule returned. Scope is MUTATING actions: file edits
+and state-changing commands (build/test/install/migrate/git-write). Pure-read commands
+(cat/ls/grep/git-log; read-only) and the recall query itself are **exempt** \u2014 no
+infinite regress. A predicate-less query is rejected; **keyword-only recall is the
+anti-pattern** \u2014 most lessons are keyed to a \`file_glob\`/\`command_pattern\` and won't
+surface (the CLI warns). Excuses ("small edit", "I already know this", "later") all
+mean: query first \u2014 skipping recall on a mutating action is a process violation, and
+the user will check.
+
+## Capture \u2014 immediately after any failure
+
+Any failure counts, not just red tests: a failing test/CI/lint/typecheck, a code
+review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's.
+
+\`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`
+
+- **At least one _effective_ trigger is required.** A capture is rejected
+  (\`UNRECALLABLE_LESSON\`) when EVERY trigger is dead on the mandatory \`--file\`/\`--cmd\`
+  recall path \u2014 a stopword-only keyword ("state of the art"), or an invalid/ReDoS
+  command regex \u2014 because the lesson could never be recalled there. Prefer
+  \`--trigger-file\`: the most reliable trigger, it fires on \`--file\` recall. A keyword
+  alone is discouraged (\`KEYWORD_ONLY_LESSON\`); paraphrasing an existing rule warns
+  (\`NEAR_DUPLICATE_LESSON\` \u2014 update that lesson instead).
+- **One imperative sentence.** A rule over 2000 chars is rejected (\`OVERSIZED_RULE\`) \u2014
+  trim it or split into separate lessons; don't paste a log/diff.
+- Widen with \`--trigger-cmd <regex>\` / \`--trigger-kw <text>\`. New area:
+  \`--new-topic --topic-summary "<line>"\` (list ids with \`agentsmesh lessons topics\`).
+
+## No shell? \u2014 MCP tools
+
+\`lessons_query\`, \`lessons_add\`, \`lessons_topics\`, \`lessons_show\` (inspect a topic),
+\`lessons_deprecate\` (retire). validate / prune / merge / import-md are CLI-only.
+
+## Other subcommands
+
+\`agentsmesh lessons <cmd>\`: \`show\` \xB7 \`deprecate\` (\`--superseded-by\`) \xB7 \`merge\` \xB7
+\`untrigger\` \xB7 \`strip-markers\` \xB7 \`prune\` (\`--apply\`; trims over-cap triggers, GCs
+orphan triggers/topics) \xB7 \`journal\` \xB7 \`validate\` \xB7 \`stats\` \xB7 \`import-md\`. Full
+help: \`agentsmesh lessons --help\`.
+
+## Config (\`.agentsmesh/lessons/config.json\`)
+
+\`recallLimit\` / \`recallMaxTokens\` (canonical recall caps; per-call overrides
+\`--top\` / \`--max-tokens\`). \`recallMaxTokens\` is approximate \u2014 \`rule.length / 4\`,
+not a real tokenizer. \`autoPrune: true\` (default off) auto-GCs structural cruft
+after each capture \u2014 orphan triggers/topics + non-stranding dead globs, the safe
+half of \`prune\`; never trims/strands an active lesson, git-reversible.
+
+## Dedup (opt-in)
+
+Set \`--session <id>\` (or \`AGENTSMESH_SESSION_ID\`) and lessons already delivered this
+session are suppressed, so each recall carries only what is new (\`--no-dedup\` opts
+out). With no session id, recall is fully stateless \u2014 unchanged.`;
+var LESSONS_SKILL_FILE = serializeFrontmatter(
+  { name: LESSONS_SKILL_NAME, description: LESSONS_SKILL_DESCRIPTION },
+  LESSONS_SKILL_BODY
+);
+
+// src/lessons/init.ts
+async function scaffoldLessons(projectRoot) {
+  const paths = lessonsPaths(projectRoot);
+  const created = [];
+  const updated = [];
+  const skipped = [];
+  mkdirSync(paths.base, { recursive: true });
+  await maybeAutoMigrateLessons(projectRoot);
+  if (existsSync(paths.graph)) {
+    skipped.push(paths.graph);
+  } else {
+    await mutateLessonsGraphLocked(projectRoot, () => {
+    });
+    created.push(paths.graph);
+  }
+  seedLessonsConfig(projectRoot, created, skipped);
+  seedLessonsSkill(projectRoot, created, updated, skipped);
+  const rootRuleUpdated = injectProceduralBlock(projectRoot);
+  const recallHookInjected = injectRecallHook(projectRoot);
+  const gitignoreUpdated = await ensureGitignoreEntries(projectRoot, [
+    toRelPath(projectRoot, recallLogPath(projectRoot)),
+    toRelPath(projectRoot, captureLogPath(projectRoot))
+  ]);
+  return { created, updated, skipped, rootRuleUpdated, gitignoreUpdated, recallHookInjected };
+}
+function seedLessonsSkill(projectRoot, created, updated, skipped) {
+  const skillPath = join(projectRoot, ".agentsmesh/skills", LESSONS_SKILL_NAME, "SKILL.md");
+  const desired = `${LESSONS_SKILL_FILE}
+`;
+  if (!existsSync(skillPath)) {
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, desired, "utf8");
+    created.push(skillPath);
+    return;
+  }
+  if (readFileSync(skillPath, "utf8") === desired) {
+    skipped.push(skillPath);
+    return;
+  }
+  writeFileSync(skillPath, desired, "utf8");
+  updated.push(skillPath);
+}
+function seedLessonsConfig(projectRoot, created, skipped) {
+  const configPath = lessonsPaths(projectRoot).config;
+  if (existsSync(configPath)) {
+    skipped.push(configPath);
+    return;
+  }
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(defaultLessonsConfig(), null, 2)}
+`, "utf8");
+  created.push(configPath);
+}
+function injectProceduralBlock(projectRoot) {
+  const rootRule = join(projectRoot, ".agentsmesh/rules/_root.md");
+  if (!existsSync(rootRule)) {
+    mkdirSync(dirname(rootRule), { recursive: true });
+    const seeded = `---
+root: true
+description: ""
+---
+
+${LESSONS_PARAGRAPH_BLOCK}
+
+# Operational Guidelines
+`;
+    writeFileSync(rootRule, seeded, "utf8");
+    return true;
+  }
+  const current = readFileSync(rootRule, "utf8");
+  const desired = `${appendLessonsParagraph(current)}
+`;
+  if (desired === current) return false;
+  writeFileSync(rootRule, desired, "utf8");
+  return true;
+}
+
+export { DEFAULT_RECALL_LIMIT, DEFAULT_RECALL_MAX_TOKENS, LESSONS_LOCK_FILENAME, LESSONS_PROCEDURAL_RULE, LessonsGraphExistsError, LessonsGraphSchema, UnknownTopicError, acquireLessonsLock, addLesson, captureLesson, graphFilePath, importLegacyLessons, isSafeRegexPattern, lessonsLockPath, lessonsPaths, loadLessonsGraph, maybeAutoMigrateLessons, mergeLessons, mutateLessonsGraph, parseGraph, queryLessons, rankLessons, recallLessons, scaffoldLessons, serializeGraph, stripLegacyMarkers, stripMarkersInGraph, toRelPath, tryLoadLessonsGraph, validateLessonsGraph };
+//# sourceMappingURL=lessons.js.map
+//# sourceMappingURL=lessons.js.map