agentsmesh 0.31.0 → 0.32.0

package/dist/index.js

@@ -27351,14 +27351,56 @@ async function diffOutputChecksums(rootBase, lockOutputs) {
   return { outputsModified, outputsRemoved };
 }
 
+// src/core/generate/stale-cleanup.ts
+init_fs();
+init_builtin_targets();
+async function listFiles2(root, base = root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const abs = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFiles2(abs, base));
+      continue;
+    }
+    files.push(relative(base, abs).replace(/\\/g, "/"));
+  }
+  return files;
+}
+async function findStaleGeneratedOutputs(args) {
+  const expected = new Set(args.expectedPaths);
+  const stale = /* @__PURE__ */ new Set();
+  const scope = args.scope ?? "project";
+  for (const target31 of args.targets) {
+    const managed = getTargetManagedOutputs(target31, scope);
+    if (!managed) continue;
+    for (const file of managed.files) stale.add(file);
+    for (const dir of managed.dirs) {
+      const absDir = join(args.projectRoot, dir);
+      if (!await exists(absDir)) continue;
+      for (const file of await listFiles2(absDir)) {
+        stale.add(`${dir}/${file}`.replace(/\/+/g, "/"));
+      }
+    }
+  }
+  const found = [];
+  for (const relPath of stale) {
+    if (expected.has(relPath)) continue;
+    if (await exists(join(args.projectRoot, relPath))) found.push(relPath);
+  }
+  return found.sort();
+}
+
 // src/core/check/lock-sync.ts
 async function checkLockSync(opts) {
-  const { config, configDir, canonicalDir, rootBase } = opts;
+  const { config, configDir, canonicalDir, rootBase, scope = "project" } = opts;
   const lock = await readLock(canonicalDir);
   if (lock === null) {
     return {
       inSync: false,
       hasLock: false,
+      canonicalDrift: false,
+      outputDrift: false,
       modified: [],
       added: [],
       removed: [],
@@ -27366,6 +27408,7 @@ async function checkLockSync(opts) {
       lockedViolations: [],
       outputsModified: [],
       outputsRemoved: [],
+      outputsStale: [],
       outputsChecked: false
     };
   }
@@ -27404,10 +27447,20 @@ async function checkLockSync(opts) {
   );
   const outputsChecked = rootBase !== void 0 && lock.outputs !== void 0;
   const { outputsModified, outputsRemoved } = outputsChecked ? await diffOutputChecksums(rootBase, lock.outputs ?? {}) : { outputsModified: [], outputsRemoved: [] };
-  const inSync = modified.length === 0 && added.length === 0 && removed.length === 0 && extendsModified.length === 0 && outputsModified.length === 0 && outputsRemoved.length === 0;
+  const outputsStale = rootBase !== void 0 && lock.outputs !== void 0 ? await findStaleGeneratedOutputs({
+    projectRoot: rootBase,
+    targets: [...config.targets, ...config.pluginTargets ?? []],
+    expectedPaths: Object.keys(lock.outputs),
+    scope
+  }) : [];
+  const canonicalDrift = modified.length > 0 || added.length > 0 || removed.length > 0 || extendsModified.length > 0;
+  const outputDrift = outputsModified.length > 0 || outputsRemoved.length > 0 || outputsStale.length > 0;
+  const inSync = !canonicalDrift && !outputDrift;
   return {
     inSync,
     hasLock: true,
+    canonicalDrift,
+    outputDrift,
     modified,
     added,
     removed,
@@ -27415,6 +27468,7 @@ async function checkLockSync(opts) {
     lockedViolations,
     outputsModified,
     outputsRemoved,
+    outputsStale,
     outputsChecked
   };
 }
@@ -27554,6 +27608,103 @@ function copyTargetDescriptor(descriptor31) {
 function getTargetCatalog() {
   return Object.freeze(BUILTIN_TARGETS.map(copyTargetDescriptor));
 }
+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 rel2 of LEGACY_ARTIFACT_REL) {
+    const abs = join(baseDir, rel2);
+    if (!existsSync(abs)) continue;
+    rmSync(abs, { recursive: true, force: true });
+    deleted.push(abs);
+  }
+  return deleted;
+}
 function normalizeRule2(rule) {
   return rule.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -27587,7 +27738,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);
@@ -27598,14 +27749,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);
@@ -27717,282 +27868,54 @@ function inspectCapturedLesson(graph, lessonId, knownPaths) {
       code: "STOPWORD_KEYWORD",
       message: `Lesson "${lessonId}" has keyword trigger(s) containing stopwords/short words (${stopworded.join(", ")}); recall filters them from the pattern but NOT from the file/command text, so the phrase can never match contiguously on the --file/--cmd path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art").`
     });
-  }
-  if (knownPaths !== void 0) {
-    const dead = deadFileGlobIds(graph, knownPaths);
-    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
-    if (deadHere.length > 0) {
-      warnings.push({
-        code: "DEAD_GLOB",
-        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
-      });
-    }
-    const wide = triggers.filter((t) => t.kind === "file_glob" && !isBroadGlob(t.pattern)).filter((t) => fileGlobMatchCount(t.pattern, knownPaths) > WIDE_GLOB_MATCH_COUNT).map((t) => t.pattern);
-    if (wide.length > 0) {
-      warnings.push({
-        code: "WIDE_GLOB_MATCH",
-        message: `Lesson "${lessonId}" has file glob(s) (${wide.join(", ")}) matching more than ${WIDE_GLOB_MATCH_COUNT} files in the working tree; narrow to the file-CLASS where the rule actually applies so it does not fire on unrelated edits.`
-      });
-    }
-  }
-  return warnings;
-}
-
-// src/lessons/capture-near-duplicate.ts
-var NEAR_DUPLICATE_THRESHOLD = 0.6;
-function nearDuplicateWarning(graph, lessonId) {
-  const subject = graph.lessons[lessonId];
-  if (subject === void 0) return null;
-  const subjectTokens = new Set(tokenize(subject.rule));
-  if (subjectTokens.size === 0) return null;
-  let best = null;
-  for (const [id, other] of Object.entries(graph.lessons)) {
-    if (id === lessonId || other.status !== "active") continue;
-    const otherTokens = new Set(tokenize(other.rule));
-    if (otherTokens.size === 0) continue;
-    const score = jaccard(subjectTokens, otherTokens);
-    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
-      best = { id, score };
-    }
-  }
-  if (best === null) return null;
-  return {
-    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 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 rel2 of LEGACY_ARTIFACT_REL) {
-    const abs = join(baseDir, rel2);
-    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
-  };
-}
-
-// 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 (knownPaths !== void 0) {
+    const dead = deadFileGlobIds(graph, knownPaths);
+    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
+    if (deadHere.length > 0) {
+      warnings.push({
+        code: "DEAD_GLOB",
+        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
+      });
+    }
+    const wide = triggers.filter((t) => t.kind === "file_glob" && !isBroadGlob(t.pattern)).filter((t) => fileGlobMatchCount(t.pattern, knownPaths) > WIDE_GLOB_MATCH_COUNT).map((t) => t.pattern);
+    if (wide.length > 0) {
+      warnings.push({
+        code: "WIDE_GLOB_MATCH",
+        message: `Lesson "${lessonId}" has file glob(s) (${wide.join(", ")}) matching more than ${WIDE_GLOB_MATCH_COUNT} files in the working tree; narrow to the file-CLASS where the rule actually applies so it does not fire on unrelated edits.`
       });
     }
   }
-  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();
+  return warnings;
+}
+
+// src/lessons/capture-near-duplicate.ts
+var NEAR_DUPLICATE_THRESHOLD = 0.6;
+function nearDuplicateWarning(graph, lessonId) {
+  const subject = graph.lessons[lessonId];
+  if (subject === void 0) return null;
+  const subjectTokens = new Set(tokenize(subject.rule));
+  if (subjectTokens.size === 0) return null;
+  let best = null;
+  for (const [id, other] of Object.entries(graph.lessons)) {
+    if (id === lessonId || other.status !== "active") continue;
+    const otherTokens = new Set(tokenize(other.rule));
+    if (otherTokens.size === 0) continue;
+    const score = jaccard(subjectTokens, otherTokens);
+    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
+      best = { id, score };
     }
-    g.version = CURRENT_GRAPH_VERSION;
-    g.lessons = lessons;
-    g.topics = topics;
-    g.triggers = triggers;
-  });
-  const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
+  }
+  if (best === null) return null;
   return {
-    wroteGraphPath: paths.graph,
-    deletedPaths,
-    topicCount: Object.keys(topics).length,
-    lessonCount: Object.keys(lessons).length,
-    triggerCount: triggersById.size
+    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).`
   };
 }
-
-// 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;
-  }
+function jaccard(a, b) {
+  let intersection = 0;
+  for (const t of a) if (b.has(t)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
 }
 
 // src/utils/filesystem/process-lock.ts
@@ -28293,35 +28216,135 @@ function findExistingLessonByRule(graph, ruleKey) {
   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;
+// 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 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);
+
+// 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";
   }
-  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);
+};
+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
+      });
+    }
   }
-  return coherence;
-}
-function recallLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+  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
-function captureLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
+// 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/lessons/keyword-match.ts
@@ -28409,6 +28432,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;
@@ -28502,12 +28548,21 @@ function defaultLessonsConfig() {
   return {
     recallLimit: DEFAULT_RECALL_LIMIT,
     recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
-    autoPrune: false
+    autoPrune: false,
+    repairTriggers: false
   };
 }
+function recallLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+}
+
+// src/lessons/outcome-log.ts
 function outcomeLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
 }
+function captureLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
+}
 
 // src/lessons/merge.ts
 async function mergeLessons(projectRoot, loserId, keeperId, options = {}) {