agentsmesh 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { AgentsMeshError, AgentsMeshErrorCode, CheckLockSyncOptions, ComputeDiffResult, ConfigNotFoundError, ConfigValidationError, DiffEntry, DiffSummary, FileSystemError, GenerateContext, GenerationError, ImportError, LintOptions, LintResult, LoadProjectContextOptions, LockAcquisitionError, LockSyncReport, ProjectContext, RemoteFetchError, TargetNotFoundError, check, computeDiff, diff, formatDiffSummary, generate, importFrom, lint, loadConfig, loadConfigFromDirectory, loadProjectContext, resolveOutputCollisions } from './engine.js';
 export { LoadCanonicalOptions, loadCanonical, loadCanonicalFiles } from './canonical.js';
 export { getAllDescriptors, getDescriptor, getTargetCatalog, registerTargetDescriptor } from './targets.js';
-export { A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, I as ImportLegacyOptions, d as ImportLegacyReport, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, h as LessonsGraphSchema, i as LessonsPaths, j as LessonsQuery, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, o as RankedLesson, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-B0aI-g8W.js';
+export { A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, I as ImportLegacyOptions, d as ImportLegacyReport, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, h as LessonsGraphSchema, i as LessonsPaths, j as LessonsQuery, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, o as RankedLesson, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-PvpXanVd.js';
 export { C as CanonicalAgent, a as CanonicalCommand, b as CanonicalFiles, c as CanonicalRule, d as CanonicalSkill, H as HookEntry, e as Hooks, I as IgnorePatterns, M as McpConfig, f as McpServer, P as Permissions, S as SkillSupportingFile, g as StdioMcpServer, U as UrlMcpServer, V as ValidatedConfig } from './schema-CH_JJep8.js';
 export { E as ExtraRuleOutputContext, a as ExtraRuleOutputResolver, F as FeatureLinter, G as GenerateResult, b as GeneratedOutputMerger, c as GlobalTargetSupport, I as ImportPathBuilder, d as ImportResult, L as LintDiagnostic, R as RuleLinter, S as ScopeExtrasFn, T as TargetCapabilities, e as TargetDescriptor, f as TargetGenerators, g as TargetLayout, h as TargetLayoutScope, i as TargetLintHooks, j as TargetManagedOutputs, k as TargetOutputFamily, l as TargetPathResolvers } from './target-descriptor-CaLUz7SR.js';
 import 'zod';

package/dist/index.js

@@ -2942,6 +2942,18 @@ var init_linter = __esm({
   }
 });
 
+// src/core/hook-types.ts
+var BEST_EFFORT_HOOK_EVENTS;
+var init_hook_types = __esm({
+  "src/core/hook-types.ts"() {
+    BEST_EFFORT_HOOK_EVENTS = /* @__PURE__ */ new Set([
+      "UserPromptSubmit",
+      "PostToolUseFailure",
+      "SessionStart"
+    ]);
+  }
+});
+
 // src/core/lint/shared/helpers.ts
 function createWarning(file, target31, message) {
   return {
@@ -2957,6 +2969,13 @@ function formatOxfordComma(items) {
   if (items.length === 2) return `${items[0]} and ${items[1]}`;
   return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
 }
+function unsupportedHookEventNames(hooks, supportedEvents) {
+  if (!hooks) return [];
+  const supported = new Set(supportedEvents);
+  return Object.keys(hooks).filter(
+    (event) => !supported.has(event) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+  );
+}
 function createUnsupportedHookWarning(event, target31, supportedEvents, options) {
   const by = options?.unsupportedBy ?? target31;
   const supported = formatOxfordComma(supportedEvents);
@@ -2968,6 +2987,7 @@ function createUnsupportedHookWarning(event, target31, supportedEvents, options)
 }
 var init_helpers = __esm({
   "src/core/lint/shared/helpers.ts"() {
+    init_hook_types();
   }
 });
 
@@ -6311,8 +6331,7 @@ var init_linter5 = __esm({
 // src/targets/augment-code/lint.ts
 function lintHooks3(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
-  const supportedSet = new Set(SUPPORTED_HOOK_EVENTS);
-  return Object.keys(canonical.hooks).filter((event) => !supportedSet.has(event)).map(
+  return unsupportedHookEventNames(canonical.hooks, SUPPORTED_HOOK_EVENTS).map(
     (event) => createUnsupportedHookWarning(event, "augment-code", SUPPORTED_HOOK_EVENTS, {
       unsupportedBy: "AugmentCode hooks"
     })
@@ -10317,8 +10336,7 @@ function lintCommands3(canonical) {
 function lintHooks5(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
   const supported = ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit"];
-  const supportedSet = new Set(supported);
-  const diagnostics = Object.keys(canonical.hooks).filter((event) => !supportedSet.has(event)).map(
+  const diagnostics = unsupportedHookEventNames(canonical.hooks, supported).map(
     (event) => createUnsupportedHookWarning(event, "copilot", supported, {
       unsupportedBy: "Copilot hooks"
     })
@@ -11436,7 +11454,7 @@ var init_permissions2 = __esm({
 // src/targets/cursor/hook-format.ts
 function unmappedCursorHookEvents(hooks) {
   return Object.keys(hooks).filter(
-    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_CURSOR)
+    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_CURSOR) && !BEST_EFFORT_HOOK_EVENTS.has(event)
   );
 }
 function toCursorHooks(hooks) {
@@ -11484,6 +11502,7 @@ function cursorHooksToCanonical(hooks) {
 var CANONICAL_TO_CURSOR, CURSOR_TO_CANONICAL;
 var init_hook_format = __esm({
   "src/targets/cursor/hook-format.ts"() {
+    init_hook_types();
     init_hook_command();
     CANONICAL_TO_CURSOR = {
       PreToolUse: "preToolUse",
@@ -13934,8 +13953,9 @@ function lintCommands6(canonical) {
 function lintHooks7(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
   const supported = ["PreToolUse", "PostToolUse", "Notification"];
-  const supportedSet = new Set(supported);
-  return Object.keys(canonical.hooks).filter((event) => !supportedSet.has(event)).map((event) => createUnsupportedHookWarning(event, "gemini-cli", supported));
+  return unsupportedHookEventNames(canonical.hooks, supported).map(
+    (event) => createUnsupportedHookWarning(event, "gemini-cli", supported)
+  );
 }
 var init_lint14 = __esm({
   "src/targets/gemini-cli/lint.ts"() {
@@ -16187,8 +16207,7 @@ var init_linter20 = __esm({
 function lintHooks10(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
   const supported = ["PreToolUse", "PostToolUse", "UserPromptSubmit", "SubagentStop"];
-  const supportedSet = new Set(supported);
-  return Object.keys(canonical.hooks).filter((event) => !supportedSet.has(event)).map(
+  return unsupportedHookEventNames(canonical.hooks, supported).map(
     (event) => createUnsupportedHookWarning(event, "kiro", supported, { unsupportedBy: "Kiro hooks" })
   );
 }
@@ -24283,7 +24302,8 @@ function lintRuleScopeInversion(input) {
   }
   return out2;
 }
-var CURRENT_GRAPH_VERSION = 1;
+var CURRENT_GRAPH_VERSION = 2;
+var VersionSchema = z.union([z.literal(1), z.literal(2)]);
 var MAX_RULE_LENGTH = 2e3;
 var IdSchema = z.string().regex(/^[a-z0-9-]+$/, "id must be kebab-case");
 var DateSchema = z.string().regex(
@@ -24307,10 +24327,17 @@ var LessonSchema = z.object({
   evidence: z.array(z.string().min(1)),
   status: LessonStatusSchema,
   supersededBy: IdSchema.optional(),
-  createdAt: DateSchema
+  createdAt: DateSchema,
+  /**
+   * `'always'` marks an ALWAYS-ON lesson: a universal standard delivered on
+   * every task (via the UserPromptSubmit hook / a `--always` recall) rather than
+   * matched by triggers. Such a lesson needs no trigger and is excluded from
+   * triggered recall. Absent = a normal triggered lesson.
+   */
+  scope: z.literal("always").optional()
 }).strict();
 var LessonsGraphSchema = z.object({
-  version: z.literal(CURRENT_GRAPH_VERSION),
+  version: VersionSchema,
   lessons: z.record(IdSchema, LessonSchema),
   topics: z.record(IdSchema, TopicSchema),
   triggers: z.record(IdSchema, TriggerSchema)
@@ -24375,7 +24402,7 @@ 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. Pure-read commands and recall itself are exempt.
+**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>\`.
 
@@ -25251,6 +25278,12 @@ function collectDeadFileGlobs(graph, findings, knownPaths) {
     });
   }
 }
+function fileGlobMatchCount(pattern, knownPaths) {
+  const isMatch = picomatch(pattern, { dot: true });
+  let n = 0;
+  for (const p of knownPaths) if (isMatch(p)) n += 1;
+  return n;
+}
 var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
 function collectRunnerAnchoredPatterns(graph, findings) {
   const active = activeTriggerIds(graph);
@@ -25881,7 +25914,7 @@ var UnrecallableLessonError = class extends Error {
 };
 
 // src/lessons/capture-guardrails.ts
-var NEAR_DUPLICATE_THRESHOLD = 0.6;
+var WIDE_GLOB_MATCH_COUNT = 40;
 var MAX_RECOMMENDED_TRIGGERS = 8;
 function isBroadGlob(pattern) {
   const p = pattern.trim();
@@ -25937,9 +25970,19 @@ function inspectCapturedLesson(graph, lessonId, knownPaths) {
         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;
@@ -26159,7 +26202,7 @@ async function importLegacyLessons(projectRoot, options) {
     if (options.force !== true && populated) {
       throw new LessonsGraphExistsError();
     }
-    g.version = 1;
+    g.version = CURRENT_GRAPH_VERSION;
     g.lessons = lessons;
     g.topics = topics;
     g.triggers = triggers;
@@ -26310,7 +26353,7 @@ function getHostname() {
   return hostname();
 }
 function sleep2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 
 // src/lessons/lessons-lock.ts
@@ -26326,7 +26369,7 @@ async function acquireLessonsLock(projectRoot, opts = {}) {
 
 // src/lessons/mutate.ts
 function emptyGraph() {
-  return { version: 1, lessons: {}, topics: {}, triggers: {} };
+  return { version: CURRENT_GRAPH_VERSION, lessons: {}, topics: {}, triggers: {} };
 }
 function findingKey(f) {
   return `${f.code}|${f.triggerId ?? ""}|${f.lessonId ?? ""}`;
@@ -26350,6 +26393,7 @@ async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
         `mutateLessonsGraph: refusing to write \u2014 this change introduces ${errors}. (Pre-existing graph issues are not blocking; run \`agentsmesh lessons validate\` to review and \`lessons untrigger\`/\`prune\` to repair them.)`
       );
     }
+    graph.version = CURRENT_GRAPH_VERSION;
     saveLessonsGraph(projectRoot, graph);
     return result;
   } finally {
@@ -26427,14 +26471,15 @@ function addLessonInto(graph, input, options) {
     }
     graph.topics[input.topic] = { summary: options.topicSummary };
   }
-  if (options.allowNoTrigger !== true) {
+  const skipTriggerGates = options.allowNoTrigger === true || input.scope === "always";
+  if (!skipTriggerGates) {
     const existingTriggers = existingId !== null ? graph.lessons[existingId]?.triggers.length ?? 0 : 0;
     if (countInputTriggers(input.triggers) === 0 && existingTriggers === 0) {
       throw new NoTriggerError();
     }
   }
   const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
-  if (options.allowNoTrigger !== true) {
+  if (!skipTriggerGates) {
     const resultingTriggers = existingId !== null ? union(graph.lessons[existingId].triggers, triggerIds) : triggerIds;
     const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
     if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
@@ -26448,7 +26493,9 @@ function addLessonInto(graph, input, options) {
       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 } : {}
+      ...existing.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
+      // Re-capturing a rule with --scope always promotes it to always-on.
+      ...input.scope === "always" ? { scope: "always" } : {}
     };
     return {
       id: existingId,
@@ -26468,7 +26515,8 @@ function addLessonInto(graph, input, options) {
     evidence: input.evidence === void 0 ? [] : [...input.evidence],
     status: "active",
     createdAt: input.createdAt ?? todayIso(),
-    ...input.rationale === void 0 ? {} : { rationale: input.rationale }
+    ...input.rationale === void 0 ? {} : { rationale: input.rationale },
+    ...input.scope === "always" ? { scope: "always" } : {}
   };
   const warnings = inspectCapturedLesson(graph, id, options.knownPaths);
   const nearDup = nearDuplicateWarning(graph, id);
@@ -26520,14 +26568,19 @@ function captureLogPath(projectRoot) {
 }
 
 // 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(" "));
+  if (parts.length === 0) return [];
+  const out2 = [];
+  for (const raw of parts.join(" ").split(/[^A-Za-z0-9]+/)) {
+    if (raw.length === 0) continue;
+    out2.push(raw.toLowerCase());
+    const sub = raw.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(" ").filter((t) => t.length > 0);
+    if (sub.length > 1) out2.push(...sub);
+  }
+  return out2;
 }
 function containsRun(needle, hay) {
   if (needle.length === 0) return false;
@@ -26560,6 +26613,7 @@ function queryLessons(graph, query) {
   const matched = [];
   for (const [id, lesson] of Object.entries(graph.lessons)) {
     if (lesson.status !== "active") continue;
+    if (lesson.scope === "always") continue;
     if (lesson.triggers.some((t) => matchedTriggerIds.has(t))) {
       matched.push({ id, lesson });
     }
@@ -26605,6 +26659,7 @@ var RRF_K = 60;
 var SPECIFICITY_WEIGHT = 3;
 var TOPIC_COHERENCE_WEIGHT = 2;
 var BM25_WEIGHT = 1;
+var EFFECTIVENESS_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
@@ -26641,16 +26696,20 @@ function rankLessons(graph, query, matches, options = {}) {
       specificity,
       // `id` is a matched lesson, and buildTopicCoherence keys every matched id.
       topicCoherence: coherence.get(id),
-      matchedTriggers: hitTriggers
+      matchedTriggers: hitTriggers,
+      // Absent from the log ⇒ neutral 1, so a lesson with no outcome data never
+      // sinks below one that has merely been recorded.
+      effectiveness: options.effectiveness?.get(id) ?? 1
     };
   });
   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 effRanks = rankMap(scored.map((s) => ({ id: s.id, value: s.effectiveness })));
   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)),
+    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)) + EFFECTIVENESS_WEIGHT / (RRF_K + effRanks.get(s.id)),
     reason: {
       matchedTriggers: s.matchedTriggers,
       bm25: s.bm25,
@@ -26689,6 +26748,9 @@ function defaultLessonsConfig() {
     autoPrune: false
   };
 }
+function outcomeLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
+}
 
 // src/lessons/merge.ts
 async function mergeLessons(projectRoot, loserId, keeperId, options = {}) {
@@ -26771,18 +26833,27 @@ async function stripMarkersInGraph(projectRoot, options = {}) {
   return { changedIds, changedCount: changedIds.length };
 }
 var RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
-var RECALL_HOOK_MATCHER = "Edit|Write|Bash";
-var RECALL_EVENTS = ["PreToolUse", "PostToolUse"];
-function injectEvent(doc, event) {
+var RECALL_HOOK_TOOL_MATCHER = "Edit|Write|Bash";
+var RECALL_EVENTS = [
+  { event: "PreToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
+  { event: "PostToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
+  { event: "UserPromptSubmit", matcher: "*" },
+  // Capture-on-failure nudge (see capture-nudge.ts). BEST-EFFORT: only Claude
+  // Code's passthrough hooks emit it; whitelist targets drop it without warning
+  // (BEST_EFFORT_HOOK_EVENTS). PostToolUse is success-only, so failures need this.
+  { event: "PostToolUseFailure", matcher: "*" },
+  // Reset recall dedup after a context compaction/clear (see hook.ts SessionStart).
+  // BEST-EFFORT: targets that can't represent SessionStart just keep dedup as-is.
+  { event: "SessionStart", matcher: "*" }
+];
+function injectEvent(doc, event, matcher) {
   const existing = doc.get(event);
   const seq = existing instanceof YAMLSeq ? existing : new YAMLSeq();
   const present = seq.items.some(
     (item) => item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND
   );
   if (present) return false;
-  seq.add(
-    doc.createNode({ matcher: RECALL_HOOK_MATCHER, type: "command", command: RECALL_HOOK_COMMAND })
-  );
+  seq.add(doc.createNode({ matcher, type: "command", command: RECALL_HOOK_COMMAND }));
   doc.set(event, seq);
   return true;
 }
@@ -26791,13 +26862,32 @@ function injectRecallHook(projectRoot) {
   if (!existsSync(path)) return false;
   const doc = parseDocument(readFileSync(path, "utf8"));
   let changed = false;
-  for (const event of RECALL_EVENTS) {
-    if (injectEvent(doc, event)) changed = true;
+  for (const { event, matcher } of RECALL_EVENTS) {
+    if (injectEvent(doc, event, matcher)) changed = true;
   }
   if (changed) writeFileSync(path, String(doc), "utf8");
   return changed;
 }
 
+// src/lessons/merge-driver-setup.ts
+var LESSONS_MERGE_DRIVER = "agentsmesh-lessons";
+var LESSONS_GITATTRIBUTES_ENTRY = `.agentsmesh/lessons/lessons.json merge=${LESSONS_MERGE_DRIVER}`;
+
+// src/utils/filesystem/gitattributes.ts
+init_fs();
+async function ensureGitattributesEntries(projectRoot, entries) {
+  const path = join(projectRoot, ".gitattributes");
+  const current = await readFileSafe(path) ?? "";
+  const existing = new Set(
+    current.split("\n").map((s) => s.trim()).filter((s) => s.length > 0 && !s.startsWith("#"))
+  );
+  const toAdd = entries.filter((e) => !existing.has(e.trim()));
+  if (toAdd.length === 0) return false;
+  const suffix = current.endsWith("\n") || current === "" ? "" : "\n";
+  await writeFileAtomic(path, current + suffix + toAdd.join("\n") + "\n");
+  return true;
+}
+
 // src/utils/filesystem/gitignore.ts
 init_fs();
 async function ensureGitignoreEntries(projectRoot, entries) {
@@ -26874,23 +26964,37 @@ regression / wrong assumption / surprise and you have not captured (nor stated
 \`Lesson: none\`)? The task is INCOMPLETE \u2014 and the user will check. The graph
 \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit.
 
-## Recall \u2014 before each file edit and each state-changing command
+## Recall \u2014 before each edit/command, and at task start
 
 \`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule.
 Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
-is the anti-pattern** \u2014 lessons are keyed to a \`file_glob\`/\`command_pattern\`.
+for a specific edit is the anti-pattern** \u2014 anchor those to \`--file\`/\`--cmd\`. But at the
+START of a task (or when planning), run \`agentsmesh lessons query --keyword "<the task's
+key terms>" --always\`: that surfaces the conceptual rules no file/command names PLUS the
+universal always-on lessons \u2014 the manual equivalent of the automatic prompt recall on
+hook-capable tools. Author a \`keyword\` trigger beside a \`file_glob\` on conceptual lessons
+so they are reachable both ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`).
 
 ## Capture \u2014 Gate Function (before any completion claim)
 
 1. **SELF-CRITIQUE**: any failure, correction, regression, wrong assumption,
    useful surprise, repeated friction, or non-obvious fix? Failing
    tests/lint/typecheck and user/review corrections \u2014 yours or anyone's \u2014 all count.
+   PROCESS/TOOLING surprises count too (a sandbox command that silently no-op'd, a port
+   already in use, a library's argument shape) \u2014 trigger those with \`--trigger-cmd\`. So
+   does a review finding you REVIEWED then deliberately REJECTED: capture it as a "do NOT
+   refactor" guard so the reasoning survives the session.
 2. **CAPTURE** a reusable imperative rule with an effective trigger (else say so):
-   \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>\`
+   \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>\`. Trigger on the
+   file-CLASS where it will RECUR (e.g. \`**/lib/use*Form*.ts\`), NOT the single file you
+   discovered it in \u2014 and NOT a broad \`src/**\`. If the rule is a UNIVERSAL standard that
+   applies to EVERY task (a comment/test/style convention no file or command names),
+   capture it with \`--scope always\` instead \u2014 it needs no trigger and is delivered on
+   every task.
 3. **RECEIPT**: emit \`Lesson: captured <id>\` or \`Lesson: none\`.
 
-At least one _effective_ trigger is required or the capture is rejected
-(\`UNRECALLABLE_LESSON\`); prefer \`--trigger-file\`. No shell \u2192 MCP \`lessons_query\`,
+At least one _effective_ trigger is required (or \`--scope always\` for a universal rule) or
+the capture is rejected (\`UNRECALLABLE_LESSON\`); prefer \`--trigger-file\`. No shell \u2192 MCP \`lessons_query\`,
 \`lessons_add\`, \`lessons_topics\`, \`lessons_show\`, \`lessons_deprecate\`. Run
 \`agentsmesh lessons --help\` for every subcommand and flag: query, add, topics, show,
 deprecate, merge, untrigger, strip-markers, prune, journal, validate, stats, import-md.
@@ -26936,9 +27040,21 @@ async function scaffoldLessons(projectRoot) {
   const recallHookInjected = injectRecallHook(projectRoot);
   const gitignoreUpdated = await ensureGitignoreEntries(projectRoot, [
     toRelPath(projectRoot, recallLogPath(projectRoot)),
-    toRelPath(projectRoot, captureLogPath(projectRoot))
+    toRelPath(projectRoot, captureLogPath(projectRoot)),
+    toRelPath(projectRoot, outcomeLogPath(projectRoot))
+  ]);
+  const gitattributesUpdated = await ensureGitattributesEntries(projectRoot, [
+    LESSONS_GITATTRIBUTES_ENTRY
   ]);
-  return { created, updated, skipped, rootRuleUpdated, gitignoreUpdated, recallHookInjected };
+  return {
+    created,
+    updated,
+    skipped,
+    rootRuleUpdated,
+    gitignoreUpdated,
+    gitattributesUpdated,
+    recallHookInjected
+  };
 }
 function seedLessonsSkill(projectRoot, created, updated, skipped) {
   const skillPath = join(projectRoot, ".agentsmesh/skills", LESSONS_SKILL_NAME, "SKILL.md");