@mmnto/cli 1.11.0 → 1.13.0

package/dist/commands/compile-templates.d.ts

@@ -1,3 +1,3 @@
-export declare const COMPILER_SYSTEM_PROMPT = "# Lesson Compiler \u2014 Regex Rule Extraction\n\n## Identity\nYou are a deterministic rule compiler. Your job is to read a single natural-language lesson and determine whether it can be expressed as a regex pattern that catches violations in source code diffs.\n\n## Rules\n- Output ONLY valid JSON \u2014 no markdown, no explanation, no preamble.\n- The regex will be tested against individual lines added in a git diff (lines starting with `+`).\n- The regex should catch **violations** (code that breaks the lesson's rule), NOT conformance.\n- Use JavaScript RegExp syntax.\n- Keep patterns simple and precise \u2014 avoid overly broad matches that cause false positives.\n- If the lesson describes an architectural principle, design philosophy, or conceptual guideline that cannot be expressed as a line-level regex, set `compilable` to `false`.\n- **File scoping:** Include a `fileGlobs` array to limit where the rule runs. Scope rules as tightly as possible:\n  - **By file type:** `[\"**/*.sh\", \"**/*.yml\"]` \u2014 for rules about shell or YAML syntax.\n  - **By package/directory:** `[\"packages/mcp/**/*.ts\"]` \u2014 for rules about MCP-specific patterns in a monorepo.\n  - **By exclusion:** `[\"packages/cli/**/*.ts\", \"!**/*.test.ts\"]` \u2014 exclude test files that legitimately use the flagged pattern.\n  - **Infer scope from context:** If a lesson mentions \"MCP tool returns\", \"CLI output\", \"LanceDB filters\", or a specific package, scope to that package. Only omit `fileGlobs` if the rule genuinely applies to ALL files (e.g., universal TypeScript style rules).\n  - **CRITICAL \u2014 Always use recursive glob patterns with `**/` prefix** (e.g., `**/*.ts`, `**/*.py`). Never emit shallow patterns like `*.ts` \u2014 they are not portable across glob implementations.\n  - **CRITICAL \u2014 Supported glob syntax only:**\n    - `**/*.ext` \u2014 match extension anywhere (recursive)\n    - `dir/**/*.ext` \u2014 directory + recursive + extension\n    - `dir/**` \u2014 everything under directory\n    - `dir/*.ext` \u2014 direct children only\n    - `!pattern` \u2014 negation prefix\n    - **DO NOT use** brace expansion `{a,b}`, nested globstars `**/dir/**`, or regex-style patterns.\n    - **DO NOT use** `**/*.{ts,js}`. Instead use separate entries: `[\"**/*.ts\", \"**/*.js\"]`.\n\n## Output Schema\n```json\n{\n  \"compilable\": true,\n  \"pattern\": \"regex pattern here\",\n  \"message\": \"human-readable violation message\",\n  \"fileGlobs\": [\"packages/mcp/**/*.ts\", \"!**/*.test.ts\"]\n}\n```\n\nOr if the rule genuinely applies to all file types (rare \u2014 prefer scoping):\n```json\n{\n  \"compilable\": true,\n  \"pattern\": \"regex pattern here\",\n  \"message\": \"human-readable violation message\"\n}\n```\n\nOr if the lesson cannot be compiled:\n```json\n{\n  \"compilable\": false,\n  \"reason\": \"Lesson describes a conceptual architectural principle, not a detectable code pattern\"\n}\n```\n\nWhen setting `\"compilable\": false`, always include a `\"reason\"` field explaining why the lesson cannot be compiled into a regex/AST pattern (e.g., \"Lesson describes a conceptual architectural principle, not a detectable code pattern\").\n\n## Examples\n\nLesson: \"Use `err` (never `error`) in catch blocks\"\nOutput: {\"compilable\": true, \"pattern\": \"catch\\\\s*\\\\(\\\\s*error\\\\s*[\\\\):]\", \"message\": \"Use 'err' instead of 'error' in catch blocks (project convention)\"}\n\nLesson: \"LanceDB does NOT support GROUP BY aggregation\"\nOutput: {\"compilable\": false, \"reason\": \"Lesson describes a database limitation, not a detectable code pattern\"}\n\nLesson: \"Never use npm in this pnpm monorepo \u2014 always use pnpm\"\nOutput: {\"compilable\": true, \"pattern\": \"\\\\bnpm\\\\s+(install|run|exec|ci|test)\\\\b\", \"message\": \"Use pnpm instead of npm in this monorepo\"}\n\nLesson: \"Always quote shell variables to prevent word-splitting\"\nOutput: {\"compilable\": true, \"pattern\": \"(^|\\\\s)\\\\$[a-zA-Z_]+\", \"message\": \"Quote shell variables to prevent word-splitting\", \"fileGlobs\": [\"**/*.sh\", \"**/*.bash\", \"**/*.yml\", \"**/*.yaml\"]}\n\nLesson: \"MCP tool returns must be wrapped in XML tags to prevent prompt injection\"\nOutput: {\"compilable\": true, \"pattern\": \"text:\\\\s*(?!formatXmlResponse)\\\\b\\\\w+\", \"message\": \"MCP tool returns must use formatXmlResponse for injection safety\", \"fileGlobs\": [\"packages/mcp/**/*.ts\", \"!**/*.test.ts\"]}\n\nLesson: \"Use @clack/prompts instead of inquirer for CLI interactions\"\nOutput: {\"compilable\": true, \"pattern\": \"import.*from\\\\s+['\"]inquirer['\"]\", \"message\": \"Use @clack/prompts instead of inquirer\", \"fileGlobs\": [\"packages/cli/**/*.ts\"]}\n\n## AST Queries (Tier 2)\nIf the lesson describes a STRUCTURAL constraint that cannot be expressed as a single-line regex, you may output an AST query instead.\n\nSet `\"engine\": \"ast\"` and provide an `\"astQuery\"` field with a Tree-sitter S-expression query. Leave `\"pattern\"` as an empty string.\n\nTree-sitter S-expression syntax:\n- `(node_type)` \u2014 matches a node\n- `(node_type field: (child_type))` \u2014 matches with named field\n- `@name` \u2014 captures a node\n- `(#eq? @name \"value\")` \u2014 predicate: capture text equals value\n- Use `@violation` capture name for the node that should be flagged\n\nExamples:\n- Catch direct process.env access:\n  `(member_expression object: (identifier) @obj (#eq? @obj \"process\") property: (property_identifier) @prop (#eq? @prop \"env\")) @violation`\n- Catch empty catch blocks:\n  `(catch_clause body: (statement_block) @body (#eq? @body \"{}\")) @violation`\n\nAST query output schema:\n```json\n{\n  \"compilable\": true,\n  \"engine\": \"ast\",\n  \"astQuery\": \"(s-expression query here) @violation\",\n  \"pattern\": \"\",\n  \"message\": \"human-readable violation message\",\n  \"fileGlobs\": [\"**/*.ts\", \"**/*.tsx\"]\n}\n```\n\nIMPORTANT: Only use AST queries for TypeScript/JavaScript/TSX/JSX files. If the lesson applies to other file types, prefer regex or mark as non-compilable.\n\n## ast-grep Patterns (Tier 2b \u2014 Preferred for structural rules)\nIf the lesson describes a structural constraint, prefer ast-grep patterns over regex or S-expressions.\n\nast-grep patterns look like the source code itself with $METAVAR placeholders:\n- `console.log($ARG)` \u2014 matches any console.log call\n- `process.env.$PROP` \u2014 matches any process.env access\n- `throw new Error($MSG)` \u2014 matches any Error throw\n- `useState($INIT)` \u2014 matches any useState hook\n\nSet `\"engine\": \"ast-grep\"` and provide an `\"astGrepPattern\"` field. Leave `\"pattern\"` as an empty string.\n\nast-grep output schema:\n```json\n{\n  \"compilable\": true,\n  \"engine\": \"ast-grep\",\n  \"astGrepPattern\": \"console.log($ARG)\",\n  \"pattern\": \"\",\n  \"message\": \"human-readable violation message\",\n  \"fileGlobs\": [\"**/*.ts\", \"**/*.tsx\"]\n}\n```\n\nIMPORTANT: ast-grep patterns must be single valid AST nodes. Statements like `catch ($E) {}` won't work \u2014 use regex for those.\nOnly use for TypeScript/JavaScript/TSX/JSX files.\n";
+export declare const COMPILER_SYSTEM_PROMPT = "# Lesson Compiler \u2014 Rule Extraction\n\n## Identity\nYou are a deterministic rule compiler. Your job is to read a single natural-language lesson and produce the narrowest possible pattern that catches violations in source code.\n\n## Engine Preference (follow this order)\n1. **ast-grep** \u2014 for any structural pattern involving function calls, method chains, imports, control flow, or object properties in TypeScript/JavaScript. This is the PREFERRED engine.\n2. **regex** \u2014 for simple string/keyword matches (URLs, comment patterns, import paths, config values) or non-JS file types.\n3. **ast** (Tree-sitter S-expression) \u2014 only when ast-grep cannot express the constraint.\n4. **non-compilable** \u2014 only for purely conceptual/architectural lessons with no detectable code pattern.\n\n## Rules\n- Output ONLY valid JSON \u2014 no markdown, no explanation, no preamble.\n- Regex rules are tested against individual lines added in a git diff (lines starting with `+`).\n- Patterns should catch **violations** (code that breaks the lesson's rule), NOT conformance.\n- For regex: use JavaScript RegExp syntax. Keep patterns precise \u2014 avoid `.*` between delimiters.\n- If the lesson describes an architectural principle or conceptual guideline that cannot be expressed as any pattern, set `compilable` to `false`.\n- **File scoping:** Include a `fileGlobs` array to limit where the rule runs. Scope rules as tightly as possible:\n  - **By file type:** `[\"**/*.sh\", \"**/*.yml\"]` \u2014 for rules about shell or YAML syntax.\n  - **By package/directory:** `[\"packages/mcp/**/*.ts\"]` \u2014 for rules about MCP-specific patterns in a monorepo.\n  - **By exclusion:** `[\"packages/cli/**/*.ts\", \"!**/*.test.ts\"]` \u2014 exclude test files that legitimately use the flagged pattern.\n  - **Infer scope from context:** If a lesson mentions \"MCP tool returns\", \"CLI output\", \"LanceDB filters\", or a specific package, scope to that package. Only omit `fileGlobs` if the rule genuinely applies to ALL files (e.g., universal TypeScript style rules).\n  - **CRITICAL \u2014 Always use recursive glob patterns with `**/` prefix** (e.g., `**/*.ts`, `**/*.py`). Never emit shallow patterns like `*.ts` \u2014 they are not portable across glob implementations.\n  - **CRITICAL \u2014 Supported glob syntax only:**\n    - `**/*.ext` \u2014 match extension anywhere (recursive)\n    - `dir/**/*.ext` \u2014 directory + recursive + extension\n    - `dir/**` \u2014 everything under directory\n    - `dir/*.ext` \u2014 direct children only\n    - `!pattern` \u2014 negation prefix\n    - **DO NOT use** brace expansion `{a,b}`, nested globstars `**/dir/**`, or regex-style patterns.\n    - **DO NOT use** `**/*.{ts,js}`. Instead use separate entries: `[\"**/*.ts\", \"**/*.js\"]`.\n\n## Output Schema\n```json\n{\n  \"compilable\": true,\n  \"pattern\": \"regex pattern here\",\n  \"message\": \"human-readable violation message\",\n  \"fileGlobs\": [\"packages/mcp/**/*.ts\", \"!**/*.test.ts\"]\n}\n```\n\nOr if the rule genuinely applies to all file types (rare \u2014 prefer scoping):\n```json\n{\n  \"compilable\": true,\n  \"pattern\": \"regex pattern here\",\n  \"message\": \"human-readable violation message\"\n}\n```\n\nOr if the lesson cannot be compiled:\n```json\n{\n  \"compilable\": false,\n  \"reason\": \"Lesson describes a conceptual architectural principle, not a detectable code pattern\"\n}\n```\n\nWhen setting `\"compilable\": false`, always include a `\"reason\"` field explaining why the lesson cannot be compiled into a regex/AST pattern (e.g., \"Lesson describes a conceptual architectural principle, not a detectable code pattern\").\n\n## Examples\n\nLesson: \"Use `err` (never `error`) in catch blocks\"\nOutput: {\"compilable\": true, \"pattern\": \"catch\\\\s*\\\\(\\\\s*error\\\\s*[\\\\):]\", \"message\": \"Use 'err' instead of 'error' in catch blocks (project convention)\"}\n\nLesson: \"LanceDB does NOT support GROUP BY aggregation\"\nOutput: {\"compilable\": false, \"reason\": \"Lesson describes a database limitation, not a detectable code pattern\"}\n\nLesson: \"Never use npm in this pnpm monorepo \u2014 always use pnpm\"\nOutput: {\"compilable\": true, \"pattern\": \"\\\\bnpm\\\\s+(install|run|exec|ci|test)\\\\b\", \"message\": \"Use pnpm instead of npm in this monorepo\"}\n\nLesson: \"Always quote shell variables to prevent word-splitting\"\nOutput: {\"compilable\": true, \"pattern\": \"(^|\\\\s)\\\\$[a-zA-Z_]+\", \"message\": \"Quote shell variables to prevent word-splitting\", \"fileGlobs\": [\"**/*.sh\", \"**/*.bash\", \"**/*.yml\", \"**/*.yaml\"]}\n\nLesson: \"MCP tool returns must be wrapped in XML tags to prevent prompt injection\"\nOutput: {\"compilable\": true, \"pattern\": \"text:\\\\s*(?!formatXmlResponse)\\\\b\\\\w+\", \"message\": \"MCP tool returns must use formatXmlResponse for injection safety\", \"fileGlobs\": [\"packages/mcp/**/*.ts\", \"!**/*.test.ts\"]}\n\nLesson: \"Use @clack/prompts instead of inquirer for CLI interactions\"\nOutput: {\"compilable\": true, \"pattern\": \"import.*from\\\\s+['\"]inquirer['\"]\", \"message\": \"Use @clack/prompts instead of inquirer\", \"fileGlobs\": [\"packages/cli/**/*.ts\"]}\n\n## ast-grep Patterns (PREFERRED for structural rules)\nFor TypeScript/JavaScript/TSX/JSX: **always prefer ast-grep over regex** when the violation involves function calls, method chains, imports, control flow, or object properties. ast-grep patterns look like source code with `$METAVAR` placeholders.\n\n### Cheat sheet\n- `$VAR` \u2014 matches any single expression or identifier\n- `$$$ARGS` \u2014 matches zero or more nodes (spread/rest capture)\n- Patterns match structurally, ignoring whitespace and formatting\n- Patterns are single AST nodes \u2014 one statement or expression\n\n### Simple patterns\n- `console.log($ARG)` \u2014 any console.log call\n- `process.env.$PROP` \u2014 any process.env property access\n- `JSON.parse($INPUT) as $TYPE` \u2014 unsafe type assertion on parsed JSON\n- `eval($CODE)` \u2014 any eval call\n\n### Compound patterns (method calls with specific arguments)\n- `$OBJ.replace(process.cwd(), $REPLACEMENT)` \u2014 string replace on cwd instead of path.relative\n- `new RegExp($SRC, $FLAGS + 'g')` \u2014 blindly appending regex flags\n- `$ARR.forEach(async ($ITEM) => { $$$BODY })` \u2014 async callback in forEach (drops promises)\n\n### Patterns with object properties (`$$$` spread captures)\n- `spawn($CMD, [$$$ARGS], { $$$BEFORE, shell: true, $$$AFTER })` \u2014 shell:true with array args\n- `{ $$$PROPS, password: $VAL, $$$REST }` \u2014 password in object literal\n\n### Multi-statement patterns (try/catch, if/else)\n- `try { $$$PRE; expect.fail($$$ARGS); $$$POST } catch ($ERR) { $$$CATCH }` \u2014 expect.fail in try block\n\nSet `\"engine\": \"ast-grep\"` and provide an `\"astGrepPattern\"` field. Leave `\"pattern\"` as an empty string.\n\n```json\n{\n  \"compilable\": true,\n  \"engine\": \"ast-grep\",\n  \"astGrepPattern\": \"$ARR.forEach(async ($ITEM) => { $$$BODY })\",\n  \"pattern\": \"\",\n  \"message\": \"Do not pass async functions to forEach \u2014 use for...of or Promise.all(arr.map(...))\",\n  \"fileGlobs\": [\"**/*.ts\", \"**/*.tsx\"]\n}\n```\n\nIMPORTANT: ast-grep patterns must be single valid AST nodes. Only use for TypeScript/JavaScript/TSX/JSX files.\n\n## Regex (fallback for non-structural patterns)\nUse regex ONLY when the violation is a simple string/keyword match that does not involve code structure \u2014 e.g., matching import paths, literal URLs, comment patterns, or config values. The regex rules above still apply.\n\n## AST Queries (Tree-sitter S-expressions \u2014 rarely needed)\nUse Tree-sitter S-expression queries ONLY when ast-grep cannot express the constraint (e.g., predicates on node text, child count checks).\n\nSet `\"engine\": \"ast\"` and provide an `\"astQuery\"` field with a Tree-sitter S-expression query. Leave `\"pattern\"` as an empty string.\n\nTree-sitter S-expression syntax:\n- `(node_type)` \u2014 matches a node\n- `(node_type field: (child_type))` \u2014 matches with named field\n- `@name` \u2014 captures a node\n- `(#eq? @name \"value\")` \u2014 predicate: capture text equals value\n- Use `@violation` capture name for the node that should be flagged\n\n```json\n{\n  \"compilable\": true,\n  \"engine\": \"ast\",\n  \"astQuery\": \"(catch_clause body: (statement_block) @body (#eq? @body \"{}\")) @violation\",\n  \"pattern\": \"\",\n  \"message\": \"human-readable violation message\",\n  \"fileGlobs\": [\"**/*.ts\", \"**/*.tsx\"]\n}\n```\n\nIMPORTANT: Only use AST queries for TypeScript/JavaScript/TSX/JSX files.\n";
 export declare const PIPELINE3_COMPILER_PROMPT = "# Example-Based Rule Compiler \u2014 Pipeline 3\n\n## Identity\nYou are a deterministic rule compiler. Your job is to analyze Bad and Good code snippets and generate a regex pattern that catches the BAD pattern but NOT the good pattern.\n\n## Input\nYou will receive:\n1. A lesson heading describing the rule\n2. **Bad Code** \u2014 code that should trigger the rule (violations)\n3. **Good Code** \u2014 code that should NOT trigger (correct alternatives)\n4. The full lesson body for additional context\n\n## Strategy\n1. Identify the structural difference between Bad and Good code\n2. Find a regex pattern that matches the BAD lines but not the GOOD lines\n3. The pattern will be tested line-by-line against git diff additions\n4. Keep patterns precise \u2014 avoid overly broad matches\n\n## Rules\n- Output ONLY valid JSON \u2014 no markdown, no explanation\n- The regex must use JavaScript RegExp syntax\n- The pattern MUST match at least one Bad line and MUST NOT match any Good line\n- Include fileGlobs to scope the rule appropriately\n- **CRITICAL \u2014 Always use recursive glob patterns with `**/` prefix** (e.g., `**/*.ts`, `**/*.py`)\n- **CRITICAL \u2014 Supported glob syntax only:** `**/*.ext`, `dir/**/*.ext`, `!pattern` for negation. NO brace expansion.\n\n## Output Schema\n```json\n{\n  \"compilable\": true,\n  \"pattern\": \"regex pattern that catches Bad but not Good\",\n  \"message\": \"human-readable violation message\",\n  \"fileGlobs\": [\"**/*.ts\", \"!**/*.test.ts\"]\n}\n```\n\nOr if the difference cannot be expressed as a line-level regex:\n```json\n{\n  \"compilable\": false,\n  \"reason\": \"Explanation of why a regex cannot distinguish these snippets\"\n}\n```\n";
 //# sourceMappingURL=compile-templates.d.ts.map

package/dist/commands/compile-templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-templates.d.ts","sourceRoot":"","sources":["../../src/commands/compile-templates.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,w/NAqIlC,CAAC;AAIF,eAAO,MAAM,yBAAyB,4qDA2CrC,CAAC"}
+{"version":3,"file":"compile-templates.d.ts","sourceRoot":"","sources":["../../src/commands/compile-templates.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,29QAsJlC,CAAC;AAIF,eAAO,MAAM,yBAAyB,4qDA2CrC,CAAC"}

package/dist/commands/compile-templates.js

@@ -1,16 +1,21 @@
 // ─── Compiler prompt ────────────────────────────────
-export const COMPILER_SYSTEM_PROMPT = `# Lesson Compiler — Regex Rule Extraction
+export const COMPILER_SYSTEM_PROMPT = `# Lesson Compiler — Rule Extraction
 
 ## Identity
-You are a deterministic rule compiler. Your job is to read a single natural-language lesson and determine whether it can be expressed as a regex pattern that catches violations in source code diffs.
+You are a deterministic rule compiler. Your job is to read a single natural-language lesson and produce the narrowest possible pattern that catches violations in source code.
+
+## Engine Preference (follow this order)
+1. **ast-grep** — for any structural pattern involving function calls, method chains, imports, control flow, or object properties in TypeScript/JavaScript. This is the PREFERRED engine.
+2. **regex** — for simple string/keyword matches (URLs, comment patterns, import paths, config values) or non-JS file types.
+3. **ast** (Tree-sitter S-expression) — only when ast-grep cannot express the constraint.
+4. **non-compilable** — only for purely conceptual/architectural lessons with no detectable code pattern.
 
 ## Rules
 - Output ONLY valid JSON — no markdown, no explanation, no preamble.
-- The regex will be tested against individual lines added in a git diff (lines starting with \`+\`).
-- The regex should catch **violations** (code that breaks the lesson's rule), NOT conformance.
-- Use JavaScript RegExp syntax.
-- Keep patterns simple and precise — avoid overly broad matches that cause false positives.
-- If the lesson describes an architectural principle, design philosophy, or conceptual guideline that cannot be expressed as a line-level regex, set \`compilable\` to \`false\`.
+- Regex rules are tested against individual lines added in a git diff (lines starting with \`+\`).
+- Patterns should catch **violations** (code that breaks the lesson's rule), NOT conformance.
+- For regex: use JavaScript RegExp syntax. Keep patterns precise — avoid \`.*\` between delimiters.
+- If the lesson describes an architectural principle or conceptual guideline that cannot be expressed as any pattern, set \`compilable\` to \`false\`.
 - **File scoping:** Include a \`fileGlobs\` array to limit where the rule runs. Scope rules as tightly as possible:
   - **By file type:** \`["**/*.sh", "**/*.yml"]\` — for rules about shell or YAML syntax.
   - **By package/directory:** \`["packages/mcp/**/*.ts"]\` — for rules about MCP-specific patterns in a monorepo.
@@ -75,63 +80,75 @@ Output: {"compilable": true, "pattern": "text:\\\\s*(?!formatXmlResponse)\\\\b\\
 Lesson: "Use @clack/prompts instead of inquirer for CLI interactions"
 Output: {"compilable": true, "pattern": "import.*from\\\\s+['\"]inquirer['\"]", "message": "Use @clack/prompts instead of inquirer", "fileGlobs": ["packages/cli/**/*.ts"]}
 
-## AST Queries (Tier 2)
-If the lesson describes a STRUCTURAL constraint that cannot be expressed as a single-line regex, you may output an AST query instead.
+## ast-grep Patterns (PREFERRED for structural rules)
+For TypeScript/JavaScript/TSX/JSX: **always prefer ast-grep over regex** when the violation involves function calls, method chains, imports, control flow, or object properties. ast-grep patterns look like source code with \`$METAVAR\` placeholders.
 
-Set \`"engine": "ast"\` and provide an \`"astQuery"\` field with a Tree-sitter S-expression query. Leave \`"pattern"\` as an empty string.
+### Cheat sheet
+- \`$VAR\` — matches any single expression or identifier
+- \`$$$ARGS\` — matches zero or more nodes (spread/rest capture)
+- Patterns match structurally, ignoring whitespace and formatting
+- Patterns are single AST nodes — one statement or expression
 
-Tree-sitter S-expression syntax:
-- \`(node_type)\` — matches a node
-- \`(node_type field: (child_type))\` — matches with named field
-- \`@name\` — captures a node
-- \`(#eq? @name "value")\` — predicate: capture text equals value
-- Use \`@violation\` capture name for the node that should be flagged
+### Simple patterns
+- \`console.log($ARG)\` — any console.log call
+- \`process.env.$PROP\` — any process.env property access
+- \`JSON.parse($INPUT) as $TYPE\` — unsafe type assertion on parsed JSON
+- \`eval($CODE)\` — any eval call
+
+### Compound patterns (method calls with specific arguments)
+- \`$OBJ.replace(process.cwd(), $REPLACEMENT)\` — string replace on cwd instead of path.relative
+- \`new RegExp($SRC, $FLAGS + 'g')\` — blindly appending regex flags
+- \`$ARR.forEach(async ($ITEM) => { $$$BODY })\` — async callback in forEach (drops promises)
+
+### Patterns with object properties (\`$$$\` spread captures)
+- \`spawn($CMD, [$$$ARGS], { $$$BEFORE, shell: true, $$$AFTER })\` — shell:true with array args
+- \`{ $$$PROPS, password: $VAL, $$$REST }\` — password in object literal
 
-Examples:
-- Catch direct process.env access:
-  \`(member_expression object: (identifier) @obj (#eq? @obj "process") property: (property_identifier) @prop (#eq? @prop "env")) @violation\`
-- Catch empty catch blocks:
-  \`(catch_clause body: (statement_block) @body (#eq? @body "{}")) @violation\`
+### Multi-statement patterns (try/catch, if/else)
+- \`try { $$$PRE; expect.fail($$$ARGS); $$$POST } catch ($ERR) { $$$CATCH }\` — expect.fail in try block
+
+Set \`"engine": "ast-grep"\` and provide an \`"astGrepPattern"\` field. Leave \`"pattern"\` as an empty string.
 
-AST query output schema:
 \`\`\`json
 {
   "compilable": true,
-  "engine": "ast",
-  "astQuery": "(s-expression query here) @violation",
+  "engine": "ast-grep",
+  "astGrepPattern": "$ARR.forEach(async ($ITEM) => { $$$BODY })",
   "pattern": "",
-  "message": "human-readable violation message",
+  "message": "Do not pass async functions to forEach — use for...of or Promise.all(arr.map(...))",
   "fileGlobs": ["**/*.ts", "**/*.tsx"]
 }
 \`\`\`
 
-IMPORTANT: Only use AST queries for TypeScript/JavaScript/TSX/JSX files. If the lesson applies to other file types, prefer regex or mark as non-compilable.
+IMPORTANT: ast-grep patterns must be single valid AST nodes. Only use for TypeScript/JavaScript/TSX/JSX files.
 
-## ast-grep Patterns (Tier 2b — Preferred for structural rules)
-If the lesson describes a structural constraint, prefer ast-grep patterns over regex or S-expressions.
+## Regex (fallback for non-structural patterns)
+Use regex ONLY when the violation is a simple string/keyword match that does not involve code structure — e.g., matching import paths, literal URLs, comment patterns, or config values. The regex rules above still apply.
 
-ast-grep patterns look like the source code itself with $METAVAR placeholders:
-- \`console.log($ARG)\` — matches any console.log call
-- \`process.env.$PROP\` — matches any process.env access
-- \`throw new Error($MSG)\` — matches any Error throw
-- \`useState($INIT)\` — matches any useState hook
+## AST Queries (Tree-sitter S-expressions — rarely needed)
+Use Tree-sitter S-expression queries ONLY when ast-grep cannot express the constraint (e.g., predicates on node text, child count checks).
 
-Set \`"engine": "ast-grep"\` and provide an \`"astGrepPattern"\` field. Leave \`"pattern"\` as an empty string.
+Set \`"engine": "ast"\` and provide an \`"astQuery"\` field with a Tree-sitter S-expression query. Leave \`"pattern"\` as an empty string.
+
+Tree-sitter S-expression syntax:
+- \`(node_type)\` — matches a node
+- \`(node_type field: (child_type))\` — matches with named field
+- \`@name\` — captures a node
+- \`(#eq? @name "value")\` — predicate: capture text equals value
+- Use \`@violation\` capture name for the node that should be flagged
 
-ast-grep output schema:
 \`\`\`json
 {
   "compilable": true,
-  "engine": "ast-grep",
-  "astGrepPattern": "console.log($ARG)",
+  "engine": "ast",
+  "astQuery": "(catch_clause body: (statement_block) @body (#eq? @body \"{}\")) @violation",
   "pattern": "",
   "message": "human-readable violation message",
   "fileGlobs": ["**/*.ts", "**/*.tsx"]
 }
 \`\`\`
 
-IMPORTANT: ast-grep patterns must be single valid AST nodes. Statements like \`catch ($E) {}\` won't work — use regex for those.
-Only use for TypeScript/JavaScript/TSX/JSX files.
+IMPORTANT: Only use AST queries for TypeScript/JavaScript/TSX/JSX files.
 `;
 // ─── Pipeline 3: Example-based compilation ──────────
 export const PIPELINE3_COMPILER_PROMPT = `# Example-Based Rule Compiler — Pipeline 3

package/dist/commands/compile-templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"compile-templates.js","sourceRoot":"","sources":["../../src/commands/compile-templates.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqIrC,CAAC;AAEF,uDAAuD;AAEvD,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CxC,CAAC"}
+{"version":3,"file":"compile-templates.js","sourceRoot":"","sources":["../../src/commands/compile-templates.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJrC,CAAC;AAEF,uDAAuD;AAEvD,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CxC,CAAC"}

package/dist/commands/compile-upgrade.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compile-upgrade.test.d.ts.map

package/dist/commands/compile-upgrade.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-upgrade.test.d.ts","sourceRoot":"","sources":["../../src/commands/compile-upgrade.test.ts"],"names":[],"mappings":""}

package/dist/commands/compile-upgrade.test.js

@@ -0,0 +1,161 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { hashLesson } from '@mmnto/totem';
+import { cleanTmpDir } from '../test-utils.js';
+import { buildTelemetryPrefix, compileCommand } from './compile.js';
+// ─── Helpers ─────────────────────────────────────────
+function makeTmpDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'totem-compile-upgrade-'));
+}
+function setupWorkspace(tmpDir, lessonFiles) {
+    // Minimal Lite-tier config so loadConfig succeeds. No orchestrator → no LLM call.
+    fs.writeFileSync(path.join(tmpDir, 'totem.yaml'), [
+        'targets:',
+        '  - glob: "**/*.ts"',
+        '    type: code',
+        '    strategy: typescript-ast',
+        'totemDir: .totem',
+    ].join('\n') + '\n', 'utf-8');
+    const lessonsDir = path.join(tmpDir, '.totem', 'lessons');
+    fs.mkdirSync(lessonsDir, { recursive: true });
+    for (const [name, body] of Object.entries(lessonFiles)) {
+        fs.writeFileSync(path.join(lessonsDir, name), body, 'utf-8');
+    }
+}
+/** Build a valid `## Lesson —` markdown block that readAllLessons can parse. */
+function lessonMarkdown(heading, body) {
+    return `## Lesson — ${heading}\n\n**Tags:** test\n\n${body}\n`;
+}
+// ─── buildTelemetryPrefix ──────────────────────────
+describe('buildTelemetryPrefix', () => {
+    it('builds a directive describing the non-code ratio', () => {
+        const prefix = buildTelemetryPrefix({
+            code: 2,
+            string: 5,
+            comment: 3,
+            regex: 0,
+            unknown: 0,
+        });
+        // 8 non-code / 10 total = 80%
+        expect(prefix).toContain('80%');
+        expect(prefix).toContain('strings: 5');
+        expect(prefix).toContain('comments: 3');
+        expect(prefix).toContain('regex literals: 0');
+        expect(prefix).toContain('ast-grep');
+    });
+    it('reports 0% when all matches are in code', () => {
+        const prefix = buildTelemetryPrefix({
+            code: 10,
+            string: 0,
+            comment: 0,
+            regex: 0,
+            unknown: 0,
+        });
+        expect(prefix).toContain('0%');
+    });
+    it('does not divide by zero when there are no matches', () => {
+        const prefix = buildTelemetryPrefix({
+            code: 0,
+            string: 0,
+            comment: 0,
+            regex: 0,
+            unknown: 0,
+        });
+        expect(prefix).toContain('0%');
+    });
+    it('excludes the unknown bucket from both numerator and denominator', () => {
+        // 100 unclassified historical hits + 5 recent classified (all code).
+        // Old math would report (100 + 0) / 105 = 95% "non-code" — a false positive.
+        // New math: 0 / 5 = 0% non-code. Unknown is surfaced as a side note.
+        const prefix = buildTelemetryPrefix({
+            code: 5,
+            string: 0,
+            comment: 0,
+            regex: 0,
+            unknown: 100,
+        });
+        expect(prefix).toContain('0%');
+        expect(prefix).toContain('Unclassified (historical) matches: 100');
+    });
+    it('computes the ratio from classified buckets only when unknown is large', () => {
+        // 500 historical + 5 classified (2 code, 3 string). Classified total = 5,
+        // non-code = 3, pct = 60%. Unknown is reported but does not move the ratio.
+        const prefix = buildTelemetryPrefix({
+            code: 2,
+            string: 3,
+            comment: 0,
+            regex: 0,
+            unknown: 500,
+        });
+        expect(prefix).toContain('60%');
+        expect(prefix).toContain('Unclassified (historical) matches: 500');
+    });
+});
+// ─── compileCommand --upgrade error paths ──────────
+describe('compileCommand --upgrade', () => {
+    let tmpDir;
+    let originalCwd;
+    beforeEach(() => {
+        tmpDir = makeTmpDir();
+        originalCwd = process.cwd();
+        process.chdir(tmpDir);
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        cleanTmpDir(tmpDir);
+    });
+    it('errors cleanly when --upgrade hash matches no lesson', async () => {
+        setupWorkspace(tmpDir, {
+            'rule-a.md': lessonMarkdown('Use err in catch', 'Do not use error in catch blocks.'),
+        });
+        await expect(compileCommand({ upgrade: 'deadbeefcafebabe' })).rejects.toMatchObject({
+            code: 'UPGRADE_HASH_NOT_FOUND',
+        });
+    });
+    it('rejects --upgrade combined with --cloud (not yet supported)', async () => {
+        setupWorkspace(tmpDir, {
+            'rule-a.md': lessonMarkdown('Use err in catch', 'Do not use error in catch blocks.'),
+        });
+        await expect(compileCommand({ upgrade: 'deadbeef', cloud: 'https://example.invalid' })).rejects.toMatchObject({
+            code: 'UPGRADE_CLOUD_UNSUPPORTED',
+        });
+    });
+    it('rejects --upgrade combined with --force', async () => {
+        setupWorkspace(tmpDir, {
+            'rule-a.md': lessonMarkdown('Use err in catch', 'Do not use error in catch blocks.'),
+        });
+        // --force would empty the cache before scoped eviction runs, silently
+        // turning --upgrade into a full recompile. Must be rejected.
+        await expect(compileCommand({ upgrade: 'deadbeef', force: true })).rejects.toMatchObject({
+            code: 'CONFIG_INVALID',
+        });
+    });
+    it('matches a known lesson by full hash and proceeds past the filter', async () => {
+        setupWorkspace(tmpDir, {
+            'rule-a.md': lessonMarkdown('Use err in catch', 'Do not use error in catch blocks.'),
+            'rule-b.md': lessonMarkdown('Avoid console.log', 'Do not commit console.log calls.'),
+        });
+        // Compute the hash that the parser will produce for rule-a
+        const hashA = hashLesson('Use err in catch', 'Do not use error in catch blocks.');
+        // The Lite-tier config has no orchestrator, so once the upgrade filter passes,
+        // the next gate (`if (config.orchestrator)`) is skipped and we land in the
+        // export branch which throws CONFIG_MISSING. The fact that we get past
+        // UPGRADE_HASH_NOT_FOUND proves the filter matched.
+        await expect(compileCommand({ upgrade: hashA })).rejects.toMatchObject({
+            code: 'CONFIG_MISSING',
+        });
+    });
+    it('matches a known lesson by short hash prefix', async () => {
+        setupWorkspace(tmpDir, {
+            'rule-a.md': lessonMarkdown('Use err in catch', 'Do not use error in catch blocks.'),
+        });
+        const hashA = hashLesson('Use err in catch', 'Do not use error in catch blocks.');
+        const shortPrefix = hashA.slice(0, 8);
+        await expect(compileCommand({ upgrade: shortPrefix })).rejects.toMatchObject({
+            code: 'CONFIG_MISSING',
+        });
+    });
+});
+//# sourceMappingURL=compile-upgrade.test.js.map

package/dist/commands/compile-upgrade.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-upgrade.test.js","sourceRoot":"","sources":["../../src/commands/compile-upgrade.test.ts"],"names":[],"mappings":"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"}

package/dist/commands/compile.d.ts

@@ -1,4 +1,22 @@
 import type { CompiledRule, LessonInput } from '@mmnto/totem';
+/**
+ * Terminal outcome of a `--upgrade <hash>` run, returned by `compileCommand`
+ * so callers (like `totem doctor --pr` self-healing) can distinguish an actual
+ * rule replacement from a noop / skipped / failed outcome and only report real
+ * upgrades in their summaries.
+ *
+ * - `replaced`: compilation produced a fresh rule that replaced the stale copy
+ * - `skipped`:  LLM decided the lesson is non-compilable; rule moved to
+ *               nonCompilable and removed from active rules
+ * - `noop`:     compile returned with no change (rare — cache hit path)
+ * - `failed`:   transient error (network, rate limit, parser failure); old
+ *               rule is preserved untouched
+ */
+export type UpgradeStatus = 'replaced' | 'skipped' | 'noop' | 'failed';
+export interface UpgradeOutcome {
+    hash: string;
+    status: UpgradeStatus;
+}
 export interface CompileOptions {
     raw?: boolean;
     out?: string;
@@ -10,7 +28,28 @@ export interface CompileOptions {
     concurrency?: string;
     cloud?: string;
     verbose?: boolean;
+    /**
+     * Telemetry-driven re-compile (mmnto/totem#1131). Filters lessons to a single hash
+     * (full or short prefix), bypasses the cache, and threads a non-code-ratio
+     * directive into the Pipeline 2 system prompt.
+     */
+    upgrade?: string;
 }
+/**
+ * Build the directive injected into the Sonnet system prompt for `--upgrade`.
+ *
+ * `unknown` is excluded from both the numerator and the denominator because it
+ * holds historical / unclassified telemetry (pre-context-aware hits, or events
+ * where the rule runner did not provide an `astContext`). Including it would
+ * dilute the classified signal and produce misleading ratios.
+ */
+export declare function buildTelemetryPrefix(contextCounts: {
+    code: number;
+    string: number;
+    comment: number;
+    regex: number;
+    unknown: number;
+}): string;
 export interface AutoScaffoldDeps {
     fs: typeof import('node:fs');
     path: typeof import('node:path');
@@ -27,5 +66,5 @@ export interface AutoScaffoldDeps {
 }
 /** Returns true if the fixture was written, false on failure. */
 export declare function autoScaffoldFixture(lesson: LessonInput, rule: CompiledRule, deps: AutoScaffoldDeps): boolean;
-export declare function compileCommand(options: CompileOptions): Promise<void>;
+export declare function compileCommand(options: CompileOptions): Promise<UpgradeOutcome | void>;
 //# sourceMappingURL=compile.d.ts.map

package/dist/commands/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/commands/compile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAqB,WAAW,EAAE,MAAM,cAAc,CAAC;AAYjF,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAsDD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,cAAc,SAAS,CAAC,CAAC;IAC7B,IAAI,EAAE,cAAc,WAAW,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,GAAG,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAClD,mBAAmB,EAAE,cAAc,cAAc,EAAE,mBAAmB,CAAC;IACvE,qBAAqB,EAAE,cAAc,cAAc,EAAE,qBAAqB,CAAC;IAC3E,eAAe,EAAE,cAAc,cAAc,EAAE,eAAe,CAAC;IAC/D,mBAAmB,EAAE,cAAc,cAAc,EAAE,mBAAmB,CAAC;CACxE;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAyBT;AAID,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAmc3E"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/commands/compile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAqB,WAAW,EAAE,MAAM,cAAc,CAAC;AAYjF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAcT;AAsDD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,cAAc,SAAS,CAAC,CAAC;IAC7B,IAAI,EAAE,cAAc,WAAW,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,GAAG,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAClD,mBAAmB,EAAE,cAAc,cAAc,EAAE,mBAAmB,CAAC;IACvE,qBAAqB,EAAE,cAAc,cAAc,EAAE,qBAAqB,CAAC;IAC3E,eAAe,EAAE,cAAc,cAAc,EAAE,eAAe,CAAC;IAC/D,mBAAmB,EAAE,cAAc,cAAc,EAAE,mBAAmB,CAAC;CACxE;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAyBT;AAID,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAsmB5F"}