agentsmesh 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.30.0
+
+### Minor Changes
+
+- 7b795b8: Lessons: measure effectiveness and sharpen recall
+
+  The lessons subsystem now tracks whether a recalled rule actually prevented the repeat, and improves recall precision — all opt-in and backward-compatible (no change to the CLI, MCP, or `lessons.json` surface):
+  - **Effectiveness signal (opt-in via `AGENTSMESH_LESSONS_TELEMETRY=1`).** An append-only outcome log records deliveries and failures; effectiveness is derived at read time — did a delivered lesson prevent the repeat? Recall **down-ranks** a lesson that fired but never helped, `lessons validate` gains advisory `INEFFECTIVE_LESSON` and `UNCOVERED_FAILURE` findings, and `lessons stats` gains a coarse **effectiveness block** (deliveries, held rate, ineffective count). The signal is deliberately coarse and labeled as such — never presented as proof of prevention.
+  - **Diff-aware recall.** The recall hook binds on the content being written, not just the file path, so a keyword lesson can fire on the change itself.
+  - **camelCase keyword reach.** Keyword recall now also splits camelCase/acronym identifier sub-words while retaining the whole token (fully backward compatible), so a keyword like `guard` reaches `useLeaveGuard.ts`.
+  - **Quieter injection.** Automatic recall caps the injected set to the most relevant few and stays silent on no match.
+  - **Recurrence-driven capture nudge.** A failure recurring on the same action with no covering lesson escalates the capture reminder, pre-filled from the real file/command.
+  - **Portable failure detection.** The recall hook records a failure from any tool event carrying an error payload, not only Claude Code's dedicated `PostToolUseFailure` event — so effectiveness can accumulate on more harnesses.
+  - **New capture warning `WIDE_GLOB_MATCH`** flags a `file_glob` that matches a large share of the working tree, complementing the existing structural broad-glob check.
+  - **`agentsmesh init --lessons`** now commits the `.gitattributes` binding for the `lessons.json` union merge driver and prints the per-clone `git config` setup, so a team's concurrent captures merge cleanly instead of conflicting.
+
+- 7b795b8: Lessons: `--scope always` for universal always-on rules
+
+  A lesson can now be captured with `--scope always` (MCP: `scope: "always"`) for a universal standard that applies to every task — a comment/test/style convention that no single file or command names. Always-on lessons need no trigger and are delivered on every task automatically, alongside triggered recall, deduplicated once per session.
+
+### Patch Changes
+
+- 13730ca: Lint no longer warns about agentsmesh-injected best-effort hook events
+
+  `agentsmesh lint` previously flagged the recall/capture hook events agentsmesh itself injects (`UserPromptSubmit`, `PostToolUseFailure`, `SessionStart`) as "unsupported" on targets whose hook model can't represent them — an unactionable warning, since agentsmesh injects those events and degrades them gracefully. They are now excluded from the unsupported-hook warning across every whitelist-style target.
+
 ## 0.29.0
 
 ### Minor Changes

package/README.md

@@ -143,6 +143,10 @@ The memory is one git-tracked file, `.agentsmesh/lessons/lessons.json`, and ever
 - **Recall** — before an edit or a state-changing command, the agent runs `agentsmesh lessons query --file <path> --cmd <command>` and follows the rules that match.
 - **Capture** — right after a failure (red test, lint error, review comment, wrong assumption), it saves the rule with `agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>`.
 
+Rules can be **scoped** (fire only on a matching file, command, or keyword) or **always-on** (`--scope always`) for universal standards that apply to every task — delivered on each task automatically, no trigger needed.
+
+Opt in with `AGENTSMESH_LESSONS_TELEMETRY=1` and agentsmesh goes a step further — it tracks whether a recalled lesson actually **prevented** the repeat, quietly down-ranks rules that never help, and flags them in `agentsmesh lessons validate`. Off by default and per-machine; the shared graph is your rules, the effectiveness is your own history.
+
 In practice:
 
 ```bash
@@ -159,7 +163,7 @@ agentsmesh lessons query --file src/cli/output.ts
 agentsmesh init --lessons && agentsmesh generate   # wire the recall/capture loop once
 ```
 
-`init --lessons` drops a small always-on rule into `.agentsmesh/rules/_root.md` (so every target gets the habit), seeds the full operating manual as a `lessons` skill where supported, and wires a recall hook (a `PreToolUse` first-touch guard plus a `PostToolUse` fallback) on hook-capable tools; agents without shell access use the matching MCP tools (`lessons_query` / `lessons_add`). Because the graph is a normal git-tracked file, a lesson one agent learns today helps every teammate's agent tomorrow, and every change is reviewable like any other diff.
+`init --lessons` drops a small always-on rule into `.agentsmesh/rules/_root.md` (so every target gets the habit), seeds the full operating manual as a `lessons` skill where supported, and wires a recall hook on hook-capable tools — a `PreToolUse` first-touch guard plus a `PostToolUse` fallback for file/command scope, a `UserPromptSubmit` pass so conceptual (`keyword`) and always-on lessons recall against the **task text**, a `PostToolUseFailure` advisory nudge to capture at the moment something breaks, and a `SessionStart` reset so recall re-surfaces lessons a long chat has summarized away. Agents without shell access use the matching MCP tools (`lessons_query` / `lessons_add`). Because the graph is a normal git-tracked file, a lesson one agent learns today helps every teammate's agent tomorrow, and every change is reviewable like any other diff.
 
 Full walkthrough: [Teach your AI agents with lessons](https://samplexbro.github.io/agentsmesh/guides/lessons/) · [`agentsmesh lessons` reference](https://samplexbro.github.io/agentsmesh/cli/lessons/).
 

package/dist/canonical.js

@@ -2874,6 +2874,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 {
@@ -2889,6 +2901,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);
@@ -2900,6 +2919,7 @@ function createUnsupportedHookWarning(event, target31, supportedEvents, options)
 }
 var init_helpers = __esm({
   "src/core/lint/shared/helpers.ts"() {
+    init_hook_types();
   }
 });
 
@@ -6217,8 +6237,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"
     })
@@ -10223,8 +10242,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"
     })
@@ -11341,7 +11359,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) {
@@ -11389,6 +11407,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",
@@ -13839,8 +13858,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"() {
@@ -16092,8 +16112,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" })
   );
 }