agentsmesh 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 0.22.0
+
+### Minor Changes
+
+- c2a13ad: Add `agentsmesh init --lessons` and a new `agentsmesh/lessons` public API for
+  the lessons recall + capture subsystem.
+
+  The subsystem keeps agents from repeating past mistakes via a procedural rule
+  that lives in every target's root file: before any edit or command, scan
+  `.agentsmesh/lessons/index.yaml` and read every matched
+  `.agentsmesh/lessons/topics/<topic>.md`; after any failure, append to
+  `.agentsmesh/lessons/journal.md`. The optional repo-local `pnpm distill` /
+  `pnpm distill:apply` scripts can help maintain AgentsMesh's own topic routing,
+  but the generated rule does not require package-manager-specific tooling.
+
+  **Using it:**
+  - **Fresh init:** `agentsmesh init --lessons` — creates the canonical scaffold
+    AND the lessons subsystem in one command.
+  - **Retroactive add (existing project):** the same `agentsmesh init --lessons`
+    — when `agentsmesh.yaml` already exists, init only scaffolds the lessons
+    artifacts and appends the procedural rule to `_root.md`. Idempotent.
+  - After either flow, run `agentsmesh generate` to project the procedural rule
+    to every target's root file.
+
+  **Public API** (importable from `agentsmesh/lessons`):
+  - `scaffoldLessons(projectRoot)` — idempotent scaffolder used internally by
+    `init --lessons`; reusable from custom tooling.
+  - `loadLessonsIndex(projectRoot)`, `readTriggeredLessons(projectRoot, event)`,
+    `appendLessonToJournal(projectRoot, input)`, and `formatLessonBullet(input)` —
+    one high-level, target-agnostic read/write layer for integrations that should
+    not hand-roll filesystem access.
+  - `lessonsPaths(projectRoot)`, `LESSONS_PROCEDURAL_RULE`,
+    `LESSONS_JOURNAL_TEMPLATE`, `LESSONS_INDEX_TEMPLATE` — paths and templates.
+  - `parseIndex`, `LessonsIndexSchema`, `matchTriggers`, `scoreBullet`,
+    `loadLedger`, `saveLedger`, `hashBullet`, `parseBullets` — building blocks
+    for downstream tooling (custom distillers, recall hooks, IDE plugins).
+
+  **Universal across every target.** The subsystem uses plain markdown files
+  read via standard file I/O — no `Skill` tool, no description-match, no
+  per-target projection. Works in Claude Code, Codex CLI, Cline, Roo Code,
+  Cursor, Gemini CLI, Aider, Goose, and every other supported harness.
+
+  **Linter integration:** `agentsmesh lint` now validates the lessons subsystem
+  when present — checks that `index.yaml` parses, topic files referenced in the
+  index exist, and the journal file is well-formed.
+
+  **Constraints:**
+  - `--lessons` is project-mode only. Combining with `--global` errors out.
+  - Removal: `rm -rf .agentsmesh/lessons/` and strip the `## Lessons` paragraph
+    from `.agentsmesh/rules/_root.md`.
+
+### Patch Changes
+
+- c75a424: Surface marketplace sub-pack install failures instead of swallowing them silently, and route skill-pack sub-packs through the correct install path.
+- c75a424: Fix qwen-code global-mode rule embedding. Rules were silently dropped when generating in global mode; they are now embedded inline using the same pattern as other global-mode targets.
+- c75a424: Restructure the generation contract paragraph to lead with an explicit **NEVER edit generated files** prohibition naming the generated paths (`.claude/`, `.cursor/`, `AGENTS.md`, etc.), followed by **All changes MUST go through `.agentsmesh` first**. Agents were initially understanding the contract but forgetting it over multi-step conversations — front-loading the prohibition makes it stickier. All legacy contract body versions (v1-v10) remain detected for safe in-place upgrade.
+
 ## 0.21.0
 
 ### Minor Changes

package/README.md

@@ -87,6 +87,10 @@ AGENTS.md
   hooks.yaml
   permissions.yaml
   ignore
+  lessons/
+    index.yaml
+    journal.md
+    topics/
 ```
 
 ```bash
@@ -111,6 +115,12 @@ agentsmesh check      # CI-friendly drift gate against .agentsmesh/.lock
 - **`generate`** — writes `CLAUDE.md`, `AGENTS.md`, `.cursor/`, `.github/copilot-instructions.md`, etc. from canonical sources.
 - **`check`** — exits non-zero if generated files have drifted from `.agentsmesh/.lock`. Drop into CI.
 
+Use `agentsmesh init --lessons` when you want the optional lessons recall +
+capture subsystem. Agents read `.agentsmesh/lessons/index.yaml`, load only
+matching topic files before edits/commands, and append failures to
+`.agentsmesh/lessons/journal.md`; the procedural rule is projected through the
+normal root rule, so it stays tool-agnostic.
+
 If you installed via `npm install -D agentsmesh` (also `pnpm add -D` / `yarn add -D`), prefix each command with `npx`. The CLI ships as both `agentsmesh` and the shorter alias `amsh`.
 
 ---
@@ -208,6 +218,7 @@ AgentsMesh canonicalizes all of these — rules, commands, agents, skills, MCP s
 - `hooks.yaml` — pre/post tool hooks.
 - `permissions.yaml` — allow/deny rules where the target supports them.
 - `ignore` — paths the assistant should not read or modify.
+- `lessons/` — optional recall/capture memory: trigger index, append-only journal, and small topic rule files read directly by agents.
 
 Configuration:
 
@@ -222,7 +233,7 @@ Detailed contracts: [Canonical Config](https://samplexbro.github.io/agentsmesh/c
 ## CLI usage
 
 ```bash
-agentsmesh init [--global] [--yes]
+agentsmesh init [--global] [--yes] [--lessons]
 agentsmesh generate [--global] [--targets <csv>] [--check] [--dry-run] [--force] [--refresh-cache]
 agentsmesh import --from <target> [--global]
 agentsmesh convert --from <target> --to <target> [--global] [--dry-run]
@@ -384,6 +395,7 @@ Every config file ships with a generated JSON Schema, so VS Code, JetBrains, and
 | `AGENTSMESH_CACHE` | `~/.agentsmeshcache` | Override the remote-extends / tarball cache directory. |
 | `AGENTSMESH_MAX_TARBALL_MB` | `500` | Maximum GitHub tarball size in MiB the install command will accept. Allowed range: `1`–`4096`. Increase this when installing from large monorepos. |
 | `AGENTSMESH_STRICT_PLUGINS` | `0` | When set to `1`, a failed plugin descriptor import fails the build instead of warning-and-skip. Useful in CI where a missing plugin target is a regression. |
+| `AGENTSMESH_ALLOW_LOCAL_GIT` | `0` | When set to `1`, enables `git+file://` sources in `extends` and `install`. Disabled by default because on shared hosts a world-writable repo could be planted by another user and combined with elevated-artifact emission for local privilege escalation. |
 
 ---
 

package/dist/canonical.js

@@ -1050,7 +1050,7 @@ ${legacy}`, "");
   }
   return result.trim();
 }
-var ROOT_INSTRUCTION_BODY_V1, ROOT_INSTRUCTION_BODY_V2, ROOT_INSTRUCTION_BODY_V3, ROOT_INSTRUCTION_BODY_V4, ROOT_INSTRUCTION_BODY_V5, ROOT_INSTRUCTION_BODY_V6, ROOT_INSTRUCTION_BODY_V7, ROOT_INSTRUCTION_BODY_V8, ROOT_INSTRUCTION_BODY, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION, AGENTSMESH_CONTRACT_WITH_V1_BODY, AGENTSMESH_CONTRACT_WITH_V2_BODY, AGENTSMESH_CONTRACT_WITH_V3_BODY, AGENTSMESH_CONTRACT_WITH_V4_BODY, AGENTSMESH_CONTRACT_WITH_V5_BODY, AGENTSMESH_CONTRACT_WITH_V6_BODY, AGENTSMESH_CONTRACT_WITH_V7_BODY, AGENTSMESH_CONTRACT_WITH_V8_BODY, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_FORMS;
+var ROOT_INSTRUCTION_BODY_V1, ROOT_INSTRUCTION_BODY_V2, ROOT_INSTRUCTION_BODY_V3, ROOT_INSTRUCTION_BODY_V4, ROOT_INSTRUCTION_BODY_V5, ROOT_INSTRUCTION_BODY_V6, ROOT_INSTRUCTION_BODY_V7, ROOT_INSTRUCTION_BODY_V8, ROOT_INSTRUCTION_BODY_V9, ROOT_INSTRUCTION_BODY_V10, ROOT_INSTRUCTION_BODY, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION, AGENTSMESH_CONTRACT_WITH_V1_BODY, AGENTSMESH_CONTRACT_WITH_V2_BODY, AGENTSMESH_CONTRACT_WITH_V3_BODY, AGENTSMESH_CONTRACT_WITH_V4_BODY, AGENTSMESH_CONTRACT_WITH_V5_BODY, AGENTSMESH_CONTRACT_WITH_V6_BODY, AGENTSMESH_CONTRACT_WITH_V7_BODY, AGENTSMESH_CONTRACT_WITH_V8_BODY, AGENTSMESH_CONTRACT_WITH_V9_BODY, AGENTSMESH_CONTRACT_WITH_V10_BODY, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_FORMS;
 var init_root_instruction_paragraph = __esm({
   "src/targets/projection/root-instruction-paragraph.ts"() {
     init_managed_blocks();
@@ -1062,7 +1062,9 @@ var init_root_instruction_paragraph = __esm({
     ROOT_INSTRUCTION_BODY_V6 = "Create canonical files in `.agentsmesh`: `rules/_root.md` and `rules/*.md` are Markdown rules; `commands/*.md`, `agents/*.md`, and `skills/*/SKILL.md` plus supporting files use Claude-style frontmatter Markdown; `mcp.json` is MCP JSON; `hooks.yaml` and `permissions.yaml` are YAML; `ignore` is gitignore-style text. Then run `agentsmesh generate`.";
     ROOT_INSTRUCTION_BODY_V7 = "`.agentsmesh` is the only folder you edit or add these files in: `rules/_root.md` and `rules/*.md` are Markdown rules; `commands/*.md`, `agents/*.md`, and `skills/*/SKILL.md` plus supporting files use Claude-style frontmatter Markdown; `mcp.json` is MCP JSON; `hooks.yaml` and `permissions.yaml` are YAML; `ignore` is gitignore-style text. Do not edit generated tool files; run `agentsmesh generate`.";
     ROOT_INSTRUCTION_BODY_V8 = "`agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, and `merge` as needed; never edit generated tool files.";
-    ROOT_INSTRUCTION_BODY = "`agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed; never edit generated tool files.";
+    ROOT_INSTRUCTION_BODY_V9 = "`agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed; never edit generated tool files.";
+    ROOT_INSTRUCTION_BODY_V10 = "**MUST follow when changing any rule, agent, command, skill, hook, MCP server, permission, or ignore pattern.** `agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed; never edit generated tool files.";
+    ROOT_INSTRUCTION_BODY = "**NEVER edit generated files** (`.claude/`, `.cursor/`, `AGENTS.md`, `.github/copilot-instructions.md`, and similar target outputs) \u2014 `agentsmesh generate` overwrites them. **All changes MUST go through `.agentsmesh` first**: edit `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; `agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally); if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed.";
     LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = ROOT_INSTRUCTION_BODY_V1;
     LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION = `## Project-Specific Rules
 
@@ -1091,12 +1093,20 @@ ${ROOT_INSTRUCTION_BODY_V7}`;
     AGENTSMESH_CONTRACT_WITH_V8_BODY = `## AgentsMesh Generation Contract
 
 ${ROOT_INSTRUCTION_BODY_V8}`;
+    AGENTSMESH_CONTRACT_WITH_V9_BODY = `## AgentsMesh Generation Contract
+
+${ROOT_INSTRUCTION_BODY_V9}`;
+    AGENTSMESH_CONTRACT_WITH_V10_BODY = `## AgentsMesh Generation Contract
+
+${ROOT_INSTRUCTION_BODY_V10}`;
     AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = `${ROOT_CONTRACT_START}
 ## AgentsMesh Generation Contract
 
 ${ROOT_INSTRUCTION_BODY}
 ${ROOT_CONTRACT_END}`;
     LEGACY_FORMS = [
+      AGENTSMESH_CONTRACT_WITH_V10_BODY,
+      AGENTSMESH_CONTRACT_WITH_V9_BODY,
       AGENTSMESH_CONTRACT_WITH_V8_BODY,
       AGENTSMESH_CONTRACT_WITH_V7_BODY,
       AGENTSMESH_CONTRACT_WITH_V6_BODY,
@@ -15783,9 +15793,18 @@ function generateIgnore12(canonical) {
   if (!canonical.ignore || canonical.ignore.length === 0) return [];
   return [{ path: QWEN_IGNORE, content: canonical.ignore.join("\n") }];
 }
+function renderQwenGlobalInstructions(canonical) {
+  const root = canonical.rules.find((rule) => rule.root);
+  const nonRootRules = canonical.rules.filter((rule) => {
+    if (rule.root) return false;
+    return rule.targets.length === 0 || rule.targets.includes(QWEN_CODE_TARGET);
+  });
+  return appendEmbeddedRulesBlock(root?.body.trim() ?? "", nonRootRules);
+}
 var init_generator26 = __esm({
   "src/targets/qwen-code/generator.ts"() {
     init_markdown();
+    init_managed_blocks();
     init_constants21();
   }
 });
@@ -15868,6 +15887,7 @@ var init_qwen_code2 = __esm({
     };
     globalLayout22 = {
       rootInstructionPath: QWEN_GLOBAL_ROOT,
+      renderPrimaryRootInstruction: renderQwenGlobalInstructions,
       skillDir: QWEN_GLOBAL_SKILLS_DIR,
       managedOutputs: {
         dirs: [QWEN_GLOBAL_COMMANDS_DIR, QWEN_GLOBAL_AGENTS_DIR, QWEN_GLOBAL_SKILLS_DIR],