agentsmesh 0.24.0 → 0.26.0

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

@@ -457,7 +457,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 REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical \u2014 never hand-edit. Manual: the `lessons` skill.\n\n**Recall \u2014 MUST run before every file edit and every state-changing command** (build/test/install/migrate/git-write): `agentsmesh lessons query --file <path> --cmd <command>`, then apply every rule. Pure-read commands (cat/ls/grep/git-log) and the recall query itself are exempt.\n\n**Capture \u2014 MUST run immediately after any failure** (a failing test/CI/lint/typecheck, a code review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's): `agentsmesh lessons add \"<rule>\" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>`.\n\nNo shell? Use the `lessons_query` / `lessons_add` MCP tools. Skip either and the system does not exist.";
+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`.";
 
 interface ScaffoldLessonsResult {
     readonly created: string[];

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-YKxF2zpQ.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-YKxF2zpQ.js';
+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 'zod';
 
 /**

package/dist/lessons.js

@@ -571,15 +571,15 @@ function lessonsPaths(projectRoot) {
 function toRelPath(projectRoot, absolute) {
   return relative(projectRoot, absolute).split(sep).join("/");
 }
-var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
 
-Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
 
-**Recall \u2014 MUST run before every file edit and every state-changing command** (build/test/install/migrate/git-write): \`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule. Pure-read commands (cat/ls/grep/git-log) and the recall query itself are exempt.
+**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.
 
-**Capture \u2014 MUST run immediately after any failure** (a failing test/CI/lint/typecheck, a code review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's): \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+**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>\`.
 
-No shell? Use the \`lessons_query\` / \`lessons_add\` MCP tools. Skip either and the system does not exist.`;
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
 
 // src/lessons/import-legacy.ts
 var LessonsGraphExistsError = class extends Error {
@@ -1618,15 +1618,27 @@ function validateLessonsGraph(graph, options = {}) {
 function emptyGraph() {
   return { version: 1, lessons: {}, topics: {}, triggers: {} };
 }
+function findingKey(f) {
+  return `${f.code}|${f.triggerId ?? ""}|${f.lessonId ?? ""}`;
+}
+function errorSignatures(report) {
+  return new Set(report.findings.filter((f) => f.level === "error").map(findingKey));
+}
 async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
   const release = await acquireLessonsLock(projectRoot, { retries: options.retries });
   try {
     const graph = tryLoadLessonsGraph(projectRoot) ?? emptyGraph();
+    const baseline = errorSignatures(validateLessonsGraph(graph));
     const result = await mutator(graph);
     const report = validateLessonsGraph(graph);
-    if (!report.ok) {
-      const errors = report.findings.filter((f) => f.level === "error").map((f) => `${f.code}: ${f.message}`).join("; ");
-      throw new Error(`mutateLessonsGraph: refusing to write an invalid graph \u2014 ${errors}`);
+    const introduced = report.findings.filter(
+      (f) => f.level === "error" && !baseline.has(findingKey(f))
+    );
+    if (introduced.length > 0) {
+      const errors = introduced.map((f) => `${f.code}: ${f.message}`).join("; ");
+      throw new Error(
+        `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.)`
+      );
     }
     saveLessonsGraph(projectRoot, graph);
     return result;
@@ -2586,6 +2598,17 @@ ${placed}` : placed;
 }
 
 // src/targets/projection/lessons-paragraph.ts
+var LEGACY_RAW_FORMS = [
+  `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
+
+**Recall \u2014 MUST run before every file edit and every state-changing command** (build/test/install/migrate/git-write): \`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule. Pure-read commands (cat/ls/grep/git-log) and the recall query itself are exempt.
+
+**Capture \u2014 MUST run immediately after any failure** (a failing test/CI/lint/typecheck, a code review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's): \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+No shell? Use the \`lessons_query\` / \`lessons_add\` MCP tools. Skip either and the system does not exist.`
+];
 var LESSONS_PARAGRAPH_BLOCK = `${LESSONS_CONTRACT_START}
 ${LESSONS_PROCEDURAL_RULE}
 ${LESSONS_CONTRACT_END}`;
@@ -2598,9 +2621,12 @@ function stripLessonsParagraph(content) {
   return stripRawProceduralRule(withoutBlock).trim();
 }
 function stripRawProceduralRule(content) {
-  return content.replace(`
+  return [LESSONS_PROCEDURAL_RULE, ...LEGACY_RAW_FORMS].reduce(
+    (next, rule) => next.replace(`
 
-${LESSONS_PROCEDURAL_RULE}`, "").replace(LESSONS_PROCEDURAL_RULE, "");
+${rule}`, "").replace(rule, ""),
+    content
+  );
 }
 function serializeFrontmatter(frontmatter, body) {
   const keys = Object.keys(frontmatter);
@@ -2615,68 +2641,55 @@ ${body}`;
 
 // src/lessons/skill.ts
 var LESSONS_SKILL_NAME = "lessons";
-var LESSONS_SKILL_DESCRIPTION = "Full operating manual for the agentsmesh lessons system (recall + capture). Consult when running any `agentsmesh lessons` subcommand (query, add, topics, show, deprecate, merge, untrigger, strip-markers, journal, validate, stats, prune, import-md), choosing a topic or trigger flags, using the lessons MCP tools, or when unsure how to phrase or capture a lesson.";
-var LESSONS_SKILL_BODY = `# Lessons \u2014 operating manual
-
-Two commands: **Recall** before you act, **Capture** after any failure. The graph
-\`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit.
-
-## Recall \u2014 before each file edit and each state-changing command
+var LESSONS_SKILL_DESCRIPTION = "Use when about to edit a file or run a state-changing command, or after any failure, correction, or surprising result.";
+var LESSONS_SKILL_BODY = `# Lessons \u2014 operating manual (Iron Law)
 
-\`agentsmesh lessons query --file <path> --cmd <command>\` (add \`--keyword <text>\` to
-match by task), then apply every rule returned. Scope is MUTATING actions: file edits
-and state-changing commands (build/test/install/migrate/git-write). Pure-read commands
-(cat/ls/grep/git-log; read-only) and the recall query itself are **exempt** \u2014 no
-infinite regress. A predicate-less query is rejected; **keyword-only recall is the
-anti-pattern** \u2014 most lessons are keyed to a \`file_glob\`/\`command_pattern\` and won't
-surface (the CLI warns). Excuses ("small edit", "I already know this", "later") all
-mean: query first \u2014 skipping recall on a mutating action is a process violation, and
-the user will check.
+## The Iron Law
 
-## Capture \u2014 immediately after any failure
+**NO MUTATION WITHOUT RECALL. NO COMPLETION WITHOUT A CAPTURE DECISION.**
 
-Any failure counts, not just red tests: a failing test/CI/lint/typecheck, a code
-review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's.
-
-\`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`
+Violating the letter is violating the spirit. Edited a file or ran a state-changing
+command without recall? Process violation. Did the turn hit a failure / correction /
+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.
 
-- **At least one _effective_ trigger is required.** A capture is rejected
-  (\`UNRECALLABLE_LESSON\`) when EVERY trigger is dead on the mandatory \`--file\`/\`--cmd\`
-  recall path \u2014 a stopword-only keyword ("state of the art"), or an invalid/ReDoS
-  command regex \u2014 because the lesson could never be recalled there. Prefer
-  \`--trigger-file\`: the most reliable trigger, it fires on \`--file\` recall. A keyword
-  alone is discouraged (\`KEYWORD_ONLY_LESSON\`); paraphrasing an existing rule warns
-  (\`NEAR_DUPLICATE_LESSON\` \u2014 update that lesson instead).
-- **One imperative sentence.** A rule over 2000 chars is rejected (\`OVERSIZED_RULE\`) \u2014
-  trim it or split into separate lessons; don't paste a log/diff.
-- Widen with \`--trigger-cmd <regex>\` / \`--trigger-kw <text>\`. New area:
-  \`--new-topic --topic-summary "<line>"\` (list ids with \`agentsmesh lessons topics\`).
+## Recall \u2014 before each file edit and each state-changing command
 
-## No shell? \u2014 MCP tools
+\`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\`.
 
-\`lessons_query\`, \`lessons_add\`, \`lessons_topics\`, \`lessons_show\` (inspect a topic),
-\`lessons_deprecate\` (retire). validate / prune / merge / import-md are CLI-only.
+## Capture \u2014 Gate Function (before any completion claim)
 
-## Other subcommands
+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.
+2. **CAPTURE** a reusable imperative rule with an effective trigger (else say so):
+   \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>\`
+3. **RECEIPT**: emit \`Lesson: captured <id>\` or \`Lesson: none\`.
 
-\`agentsmesh lessons <cmd>\`: \`show\` \xB7 \`deprecate\` (\`--superseded-by\`) \xB7 \`merge\` \xB7
-\`untrigger\` \xB7 \`strip-markers\` \xB7 \`prune\` (\`--apply\`; trims over-cap triggers, GCs
-orphan triggers/topics) \xB7 \`journal\` \xB7 \`validate\` \xB7 \`stats\` \xB7 \`import-md\`. Full
-help: \`agentsmesh lessons --help\`.
+At least one _effective_ trigger is required 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.
 
-## Config (\`.agentsmesh/lessons/config.json\`)
+### Rationalization Prevention \u2014 these excuses mean STOP
 
-\`recallLimit\` / \`recallMaxTokens\` (canonical recall caps; per-call overrides
-\`--top\` / \`--max-tokens\`). \`recallMaxTokens\` is approximate \u2014 \`rule.length / 4\`,
-not a real tokenizer. \`autoPrune: true\` (default off) auto-GCs structural cruft
-after each capture \u2014 orphan triggers/topics + non-stranding dead globs, the safe
-half of \`prune\`; never trims/strands an active lesson, git-reversible.
+| Excuse | Reality |
+| --- | --- |
+| "Small edit / I already know this / later" | Query first \u2014 skipping recall is a process violation |
+| "Nothing reusable here" | You hit a failure/surprise \u2014 name it or capture it |
+| "My own TDD red, not a real failure" | A red you did not predict IS a lesson |
+| "I fixed one site; the twin is obvious" | Capture it \u2014 the unfixed twin is what gets missed |
+| "Different words, so the rule doesn't apply" | Spirit over letter |
 
-## Dedup (opt-in)
+## Lesson gate \u2014 before final response
 
-Set \`--session <id>\` (or \`AGENTSMESH_SESSION_ID\`) and lessons already delivered this
-session are suppressed, so each recall carries only what is new (\`--no-dedup\` opts
-out). With no session id, recall is fully stateless \u2014 unchanged.`;
+The final response MUST carry the receipt: \`Lesson: captured <id>\` or \`Lesson: none\`.
+No receipt = task incomplete. Do not capture one-off facts, task summaries, or project
+context \u2014 only reusable imperative rules with an effective trigger.`;
 var LESSONS_SKILL_FILE = serializeFrontmatter(
   { name: LESSONS_SKILL_NAME, description: LESSONS_SKILL_DESCRIPTION },
   LESSONS_SKILL_BODY