agentsmesh 0.30.2 → 0.32.0

package/dist/lessons.js

@@ -1,9 +1,9 @@
 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 { resolve, dirname, join, relative, sep, basename, extname } from 'path';
 import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
+import { createHash } from 'crypto';
+import picomatch from 'picomatch';
 import { mkdir, rm, writeFile, readFile, stat, lstat, unlink, rename, chmod } from 'fs/promises';
 import { tmpdir, hostname } from 'os';
 import 'timers/promises';
@@ -52,6 +52,157 @@ var LessonsGraphSchema = z.object({
 function parseGraph(raw) {
   return LessonsGraphSchema.parse(raw);
 }
+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 = makeTriggerId(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_PREFIX = {
+  file_glob: "glob",
+  command_pattern: "cmd",
+  keyword: "kw"
+};
+function makeTriggerId(spec) {
+  const hash = createHash("sha1").update(`${spec.kind}|${spec.pattern}`).digest("hex").slice(0, 8);
+  return `t-${TRIGGER_PREFIX[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;
+}
 function normalizeRule(rule) {
   return rule.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -85,7 +236,7 @@ function mergeTriggers(graph, spec) {
       if (!triggerIds.includes(existing)) triggerIds.push(existing);
       continue;
     }
-    const id = makeTriggerId(spec2);
+    const id = makeTriggerId2(spec2);
     graph.triggers[id] = { kind: spec2.kind, pattern: spec2.pattern };
     reverseLookup.set(key, id);
     triggerIds.push(id);
@@ -96,14 +247,14 @@ function mergeTriggers(graph, spec) {
 function triggerKey(t) {
   return `${t.kind}|${t.pattern}`;
 }
-var TRIGGER_PREFIX = {
+var TRIGGER_PREFIX2 = {
   file_glob: "glob",
   command_pattern: "cmd",
   keyword: "kw"
 };
-function makeTriggerId(spec) {
+function makeTriggerId2(spec) {
   const hash = createHash("sha1").update(triggerKey(spec)).digest("hex").slice(0, 8);
-  return `t-${TRIGGER_PREFIX[spec.kind]}-${hash}`;
+  return `t-${TRIGGER_PREFIX2[spec.kind]}-${hash}`;
 }
 function makeLessonId(graph, topic, ruleKey) {
   const slug = ruleToSlug(ruleKey);
@@ -397,338 +548,32 @@ function jaccard(a, b) {
   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))
-    };
+
+// src/core/errors.ts
+var AgentsMeshError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "AgentsMeshError";
+    this.code = code;
   }
-}
-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
+};
+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
     );
-    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)
-
-Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
-
-**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
-
-**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
-
-**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
-
-// 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 = CURRENT_GRAPH_VERSION;
-    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;
+    this.name = "LockAcquisitionError";
+    this.lockPath = lockPath;
+    this.holder = holder;
+    this.label = label;
   }
 };
 var FileSystemError = class extends AgentsMeshError {
@@ -1781,239 +1626,185 @@ function addLessonInto(graph, input, options) {
   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 },
-    ...input.scope === "always" ? { scope: "always" } : {}
-  };
-  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);
+    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 },
+    ...input.scope === "always" ? { scope: "always" } : {}
+  };
+  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 readJsonl(path) {
-  if (!existsSync(path)) return [];
-  const out = [];
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    if (line.trim().length === 0) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch {
-    }
+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 out;
+  return null;
 }
-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;
+
+// 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
+  };
 }
-function recallLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+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 isTelemetryEnabled(env = process.env) {
-  return env[TELEMETRY_ENV] === "1";
+function toRelPath(projectRoot, absolute) {
+  return relative(projectRoot, absolute).split(sep).join("/");
 }
-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
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
+
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+
+**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
+
+// 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 = CURRENT_GRAPH_VERSION;
+    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/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
-  });
+// 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}`;
 }
-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
-  );
+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;
+  }
 }
 function normalizeRecallFile(file, projectRoot) {
   const forward = file.replaceAll("\\", "/");
@@ -2035,28 +1826,6 @@ function safeRealpath(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 deriveHaystackTokens(query) {
@@ -2143,6 +1912,29 @@ function triggerMatches(trigger, query, budget) {
   }
 }
 
+// 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/ranking.ts
 var DEFAULT_RECALL_LIMIT = 10;
 var DEFAULT_RECALL_MAX_TOKENS = 400;
@@ -2236,7 +2028,8 @@ function defaultLessonsConfig() {
   return {
     recallLimit: DEFAULT_RECALL_LIMIT,
     recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
-    autoPrune: false
+    autoPrune: false,
+    repairTriggers: false
   };
 }
 function positiveInt(value) {
@@ -2261,6 +2054,57 @@ function loadRecallConfig(projectRoot) {
     return fallback;
   }
 }
+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);
+}
+function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+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/outcome-log.ts
 function outcomeLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
 }
@@ -2377,14 +2221,17 @@ async function recallLessons(projectRoot, query, options = {}) {
       dedup,
       lessons.map((l) => l.id)
     );
-  recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, { bypassed: false });
+  recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, {
+    bypassed: false,
+    session: options.sessionId
+  });
   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();
+  const session = options.session ?? sessionId();
   appendRecallRecord(projectRoot, {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     hasFile: query.file !== void 0,
@@ -2404,6 +2251,255 @@ function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, opti
     ...session !== void 0 ? { session } : {}
   });
 }
+
+// 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;
+}
+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
+  );
+}
+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;
+}
+function isTriggerRepairEnabled(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.repairTriggers === true;
+  } catch {
+    return false;
+  }
+}
+function evidencePath(evidence, knownPaths) {
+  for (const entry of evidence ?? []) {
+    const candidate = entry.replaceAll("\\", "/").replace(/(:\d+)+$/, "").trim();
+    if (knownPaths.has(candidate)) return candidate;
+  }
+  return void 0;
+}
+function classGlobFor(path) {
+  const slash = path.lastIndexOf("/");
+  const dir = slash === -1 ? "" : path.slice(0, slash + 1);
+  const base = path.slice(slash + 1);
+  const dot = base.lastIndexOf(".");
+  return `${dir}*${dot > 0 ? base.slice(dot) : ""}`;
+}
+function repairFileGlobs(files, evidence, knownPaths, repairs) {
+  const out = [];
+  for (const glob of files) {
+    const needsNarrow = knownPaths !== void 0 && (isBroadGlob(glob) || fileGlobMatchCount(glob, knownPaths) > WIDE_GLOB_MATCH_COUNT);
+    if (!needsNarrow || evidence === void 0 || !picomatch(glob, { dot: true })(evidence)) {
+      if (!out.includes(glob)) out.push(glob);
+      continue;
+    }
+    const derived = classGlobFor(evidence);
+    const derivedOk = derived !== glob && picomatch(derived, { dot: true })(evidence) && fileGlobMatchCount(derived, knownPaths) <= fileGlobMatchCount(glob, knownPaths);
+    if (!derivedOk) {
+      if (!out.includes(glob)) out.push(glob);
+      continue;
+    }
+    if (!out.includes(derived)) out.push(derived);
+    repairs.push({
+      code: "NARROWED_GLOB",
+      message: `Narrowed broad file glob "${glob}" to the evidence file's class "${derived}". Review: for general/library behavior, re-point at the file-CLASS recurrence surface (a '**/.../*Name*.ts'-style glob) where the rule will actually recur.`
+    });
+  }
+  return out;
+}
+function repairKeywords(keywords, repairs) {
+  const out = [];
+  for (const kw of keywords) {
+    const tokens = tokenize(kw);
+    if (tokens.length === 0) {
+      repairs.push({
+        code: "DROPPED_KEYWORD",
+        message: `Dropped keyword trigger "${kw}" \u2014 it tokenizes to nothing (stopwords/short words only) and can never fire.`
+      });
+      continue;
+    }
+    if (!out.includes(kw)) out.push(kw);
+    if (!keywordNeedleLosesTokens(kw) && !isLowSignalKeyword(kw)) continue;
+    const variant = tokens.slice(0, MAX_RECOMMENDED_KEYWORD_TOKENS).join(" ");
+    if (variant.toLowerCase() === kw.toLowerCase() || out.includes(variant)) continue;
+    out.push(variant);
+    repairs.push({
+      code: "KEYWORD_VARIANT_ADDED",
+      message: `Keyword trigger "${kw}" cannot match on the mandatory --file/--cmd token path; added the matchable variant "${variant}" beside it (the original still matches prompt text).`
+    });
+  }
+  return out;
+}
+function repairTriggers(input, knownPaths) {
+  const repairs = [];
+  const evidence = knownPaths === void 0 ? void 0 : evidencePath(input.evidence, knownPaths);
+  const files = input.triggers.files === void 0 ? void 0 : repairFileGlobs(input.triggers.files, evidence, knownPaths, repairs);
+  const keywords = input.triggers.keywords === void 0 ? void 0 : repairKeywords(input.triggers.keywords, repairs);
+  if (repairs.length === 0) return { input, repairs };
+  const total = (files?.length ?? 0) + (input.triggers.commands?.length ?? 0) + (keywords?.length ?? 0);
+  if (total === 0) return { input, repairs: [] };
+  return {
+    input: {
+      ...input,
+      triggers: {
+        ...files !== void 0 ? { files } : {},
+        ...input.triggers.commands !== void 0 ? { commands: input.triggers.commands } : {},
+        ...keywords !== void 0 ? { keywords } : {}
+      }
+    },
+    repairs
+  };
+}
+
+// src/lessons/capture.ts
 async function captureLesson(projectRoot, input, options = {}) {
   await maybeAutoMigrateLessons(projectRoot);
   const triggerKinds = {
@@ -2412,11 +2508,14 @@ async function captureLesson(projectRoot, input, options = {}) {
     keyword: input.triggers.keywords?.length ?? 0
   };
   const knownPaths = options.knownPaths ?? listProjectFiles(projectRoot) ?? void 0;
+  const repair = isTriggerRepairEnabled(projectRoot) ? repairTriggers(input, knownPaths) : null;
+  const effective = repair === null ? input : repair.input;
   try {
-    const result = await addLesson(projectRoot, input, { ...options, knownPaths });
-    recordCapture(projectRoot, triggerKinds, result);
+    const result = await addLesson(projectRoot, effective, { ...options, knownPaths });
+    const repaired = repair === null || repair.repairs.length === 0 ? result : { ...result, warnings: [...result.warnings, ...repair.repairs] };
+    recordCapture(projectRoot, triggerKinds, repaired);
     const autoPruned = await maybeAutoPrune(projectRoot, knownPaths);
-    return autoPruned === null ? result : { ...result, autoPruned };
+    return autoPruned === null ? repaired : { ...repaired, autoPruned };
   } catch (err) {
     recordCapture(projectRoot, triggerKinds, null);
     throw err;