agentsmesh 0.29.0 → 0.30.1

package/dist/{init-B0aI-g8W.d.ts → init-PvpXanVd.d.ts}

@@ -34,9 +34,10 @@ declare const LessonSchema: z.ZodObject<{
     }>;
     supersededBy: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodString;
+    scope: z.ZodOptional<z.ZodLiteral<"always">>;
 }, z.core.$strict>;
 declare const LessonsGraphSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+    version: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
     lessons: z.ZodRecord<z.ZodString, z.ZodObject<{
         rule: z.ZodString;
         rationale: z.ZodOptional<z.ZodString>;
@@ -50,6 +51,7 @@ declare const LessonsGraphSchema: z.ZodObject<{
         }>;
         supersededBy: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodString;
+        scope: z.ZodOptional<z.ZodLiteral<"always">>;
     }, z.core.$strict>>;
     topics: z.ZodRecord<z.ZodString, z.ZodObject<{
         summary: z.ZodString;
@@ -91,7 +93,7 @@ interface AutoPruneSummary {
  * because that lesson is captured then silently never recalled. These guardrails
  * are the warn-only complement to that single hard block.
  */
-type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'NEAR_DUPLICATE_LESSON';
+type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'WIDE_GLOB_MATCH' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'NEAR_DUPLICATE_LESSON';
 interface GuardrailWarning {
     readonly code: GuardrailCode;
     readonly message: string;
@@ -120,6 +122,8 @@ interface AddLessonInput {
     readonly evidence?: readonly string[];
     readonly rationale?: string;
     readonly createdAt?: string;
+    /** `'always'` = a universal always-on lesson (no trigger needed; gates skipped). */
+    readonly scope?: 'always';
 }
 interface AddLessonOptions {
     readonly allowNewTopic?: boolean;
@@ -197,6 +201,14 @@ interface RankOptions {
      * worse for the agent than one slightly-over-budget rule.
      */
     readonly maxTokens?: number;
+    /**
+     * Per-lesson effectiveness score in [0,1] from the outcome log (1 = always
+     * helped; absent = neutral). Fed as a LOW-weight RRF signal so a proven
+     * fire-but-fail lesson sinks below an equally-matched effective one — a
+     * corrective nudge, never a driver. Empty/absent ⇒ every lesson ties on this
+     * signal ⇒ ordering is unchanged from the pre-effectiveness ranker.
+     */
+    readonly effectiveness?: ReadonlyMap<string, number>;
 }
 /** Default recall cap: a broad trigger match returns the most-relevant few, not the whole topic. */
 declare const DEFAULT_RECALL_LIMIT = 10;
@@ -457,7 +469,7 @@ declare function toRelPath(projectRoot: string, absolute: string): string;
  * survives generate → import → generate round-trip; only the wording inside each
  * block is tightened for maximum agent compliance.
  */
-declare const LESSONS_PROCEDURAL_RULE = "## Lessons (BLOCKING)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical; never hand-edit it. Manual: `lessons` skill.\n\n**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.\n\n**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>`.\n\n**Before final:** report `Lesson: captured <id>` or `Lesson: none`. No recall/capture gate = task incomplete. No shell: use `lessons_query` / `lessons_add`.";
+declare const LESSONS_PROCEDURAL_RULE = "## Lessons (BLOCKING)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical; never hand-edit it. Manual: `lessons` skill.\n\n**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.\n\n**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>`.\n\n**Before final:** report `Lesson: captured <id>` or `Lesson: none`. No recall/capture gate = task incomplete. No shell: use `lessons_query` / `lessons_add`.";
 
 interface ScaffoldLessonsResult {
     readonly created: string[];
@@ -467,6 +479,8 @@ interface ScaffoldLessonsResult {
     readonly rootRuleUpdated: boolean;
     /** True when the recall-log gitignore entry was added to `.gitignore`. */
     readonly gitignoreUpdated: boolean;
+    /** True when the lessons.json merge-driver entry was added to `.gitattributes`. */
+    readonly gitattributesUpdated: boolean;
     /** True when the PostToolUse recall hook was injected into `hooks.yaml`. */
     readonly recallHookInjected: boolean;
 }

package/dist/lessons.d.ts

@@ -1,5 +1,5 @@
-import { o as RankedLesson, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, j as LessonsQuery } from './init-B0aI-g8W.js';
-export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, 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, _ as lessonsLockPath, 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';
+import { o as RankedLesson, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, j as LessonsQuery } from './init-PvpXanVd.js';
+export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, 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, _ as lessonsLockPath, 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';
 import 'zod';
 
 /**

package/dist/lessons.js

@@ -9,7 +9,8 @@ import { tmpdir, hostname } from 'os';
 import 'timers/promises';
 
 // src/lessons/graph-schema.ts
-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(
@@ -33,10 +34,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)
@@ -271,6 +279,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);
@@ -288,7 +302,7 @@ function collectRunnerAnchoredPatterns(graph, findings) {
 }
 
 // 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();
@@ -344,9 +358,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;
@@ -575,7 +599,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>\`.
 
@@ -644,7 +668,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;
@@ -832,7 +856,7 @@ function getHostname() {
   return hostname();
 }
 function sleep(ms) {
-  return new Promise((resolve6) => setTimeout(resolve6, ms));
+  return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 
 // src/lessons/lessons-lock.ts
@@ -1616,7 +1640,7 @@ function validateLessonsGraph(graph, options = {}) {
 
 // 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 ?? ""}`;
@@ -1640,6 +1664,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 {
@@ -1717,14 +1742,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) {
@@ -1738,7 +1764,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,
@@ -1758,7 +1786,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);
@@ -1920,6 +1949,18 @@ function capJsonl(path, maxRecords) {
 `, "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";
@@ -2018,14 +2059,19 @@ function listProjectFiles(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 out = [];
+  for (const raw of parts.join(" ").split(/[^A-Za-z0-9]+/)) {
+    if (raw.length === 0) continue;
+    out.push(raw.toLowerCase());
+    const sub = raw.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(" ").filter((t) => t.length > 0);
+    if (sub.length > 1) out.push(...sub);
+  }
+  return out;
 }
 function containsRun(needle, hay) {
   if (needle.length === 0) return false;
@@ -2058,6 +2104,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 });
     }
@@ -2103,6 +2150,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
@@ -2139,16 +2187,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,
@@ -2209,17 +2261,58 @@ function loadRecallConfig(projectRoot) {
     return fallback;
   }
 }
+function outcomeLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
+}
+function readOutcomeLog(projectRoot) {
+  return readJsonl(outcomeLogPath(projectRoot));
+}
+function scopeKey(ev) {
+  return `${ev.session ?? ""}\0${ev.contextKey}`;
+}
+function effectiveness(events) {
+  const lastFailure = /* @__PURE__ */ new Map();
+  events.forEach((ev, i) => {
+    if (ev.kind === "failure") lastFailure.set(scopeKey(ev), i);
+  });
+  const out = /* @__PURE__ */ new Map();
+  events.forEach((ev, i) => {
+    if (ev.kind !== "delivered") return;
+    const cur = out.get(ev.lessonId) ?? { delivered: 0, missed: 0 };
+    cur.delivered += 1;
+    const lf = lastFailure.get(scopeKey(ev));
+    if (lf !== void 0 && lf > i) cur.missed += 1;
+    out.set(ev.lessonId, cur);
+  });
+  return out;
+}
+function effectivenessScore(o) {
+  return o.delivered === 0 ? 1 : 1 - o.missed / o.delivered;
+}
+function loadEffectiveness(projectRoot) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [id, o] of effectiveness(readOutcomeLog(projectRoot))) {
+    map.set(id, effectivenessScore(o));
+  }
+  return map;
+}
 var SEEN_DIR = "agentsmesh-lessons-seen";
 function openSessionDedup(options = {}) {
   if (options.disabled === true) return null;
   const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
   if (id === void 0) return null;
-  const path = seenPath(id);
+  const path = seenPath(id, options.projectRoot);
   return { sessionId: id, seen: loadSeen(path), path };
 }
-function seenPath(id) {
+function shortHash(value) {
+  let h = 5381;
+  for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
+  return h.toString(36);
+}
+function seenPath(id, projectRoot) {
   const safe = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 200);
-  return join(tmpdir(), SEEN_DIR, `${safe}.json`);
+  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash(resolve(projectRoot))}`;
+  return join(tmpdir(), SEEN_DIR, `${scoped}.json`);
 }
 function loadSeen(path) {
   if (!existsSync(path)) return /* @__PURE__ */ new Set();
@@ -2265,14 +2358,25 @@ async function recallLessons(projectRoot, query, options = {}) {
   const graph = load.graph;
   const matchQuery = query.file === void 0 ? query : { ...query, file: normalizeRecallFile(query.file, projectRoot) };
   const matches = queryLessons(graph, matchQuery);
-  const dedup = openSessionDedup({ explicit: options.sessionId, disabled: options.noDedup });
+  const dedup = openSessionDedup({
+    explicit: options.sessionId,
+    disabled: options.noDedup,
+    projectRoot
+  });
   const forRank = dedup === null ? matches : filterUnseen(dedup, matches);
   const cfg = loadRecallConfig(projectRoot);
   const lessons = rankLessons(graph, matchQuery, forRank, {
     limit: options.limit ?? cfg.limit,
-    maxTokens: options.maxTokens === null ? void 0 : options.maxTokens ?? cfg.maxTokens
+    maxTokens: options.maxTokens === null ? void 0 : options.maxTokens ?? cfg.maxTokens,
+    // Down-rank proven fire-but-fail lessons (empty ⇒ neutral, so recall is
+    // unchanged until the outcome log has real signal). Read from the side-channel.
+    effectiveness: loadEffectiveness(projectRoot)
   });
-  if (dedup !== null) commitSeen(dedup, lessons.map((l) => l.id));
+  if (dedup !== null)
+    commitSeen(
+      dedup,
+      lessons.map((l) => l.id)
+    );
   recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, { bypassed: false });
   return { lessons, totalMatches: matches.length, suppressed: matches.length - forRank.length };
 }
@@ -2400,18 +2504,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;
 }
@@ -2420,12 +2533,16 @@ 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}`;
 var UTF8_BOM = "\uFEFF";
 var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".md",
@@ -2553,7 +2670,19 @@ async function writeFileAtomic(path, content, options) {
   }
 }
 
-// src/utils/filesystem/gitignore.ts
+// src/utils/filesystem/gitattributes.ts
+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;
+}
 async function ensureGitignoreEntries(projectRoot, entries) {
   const gitignorePath = join(projectRoot, ".gitignore");
   const current = await readFileSafe(gitignorePath) ?? "";
@@ -2662,23 +2791,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.
@@ -2724,9 +2867,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");