claudecode-linter 2.1.137 → 2.1.138-patch.2

package/dist/canonical-paths.js

@@ -0,0 +1,43 @@
+export const CANONICAL_ARTIFACTS = [
+    {
+        basename: "plugin.json",
+        expectedPath: ".claude-plugin/plugin.json",
+        description: "plugin manifest",
+    },
+    {
+        basename: "marketplace.json",
+        expectedPath: ".claude-plugin/marketplace.json",
+        description: "marketplace manifest",
+    },
+    {
+        basename: "hooks.json",
+        expectedPath: "hooks/hooks.json",
+        description: "plugin hooks config",
+    },
+    {
+        basename: "SKILL.md",
+        expectedPattern: "skills/*/SKILL.md",
+        description: "skill manifest",
+    },
+    {
+        basename: ".mcp.json",
+        expectedPath: ".mcp.json",
+        description: "plugin MCP server definitions",
+    },
+    {
+        basename: ".lsp.json",
+        expectedPath: ".lsp.json",
+        description: "plugin LSP server configurations",
+    },
+    {
+        basename: "monitors.json",
+        expectedPath: "monitors/monitors.json",
+        description: "plugin background-monitor declarations",
+    },
+    {
+        basename: "settings.json",
+        expectedPath: "settings.json",
+        description: "plugin default settings",
+    },
+];
+//# sourceMappingURL=canonical-paths.js.map

package/dist/contracts.js

@@ -1,5 +1,5 @@
 // Auto-generated from contracts/claude-code-contracts.json
-// Claude Code v2.1.137 — extracted 2026-05-09T00:58:59.170Z
+// Claude Code v2.1.138 — extracted 2026-05-09T06:52:55.909Z
 // Do not edit manually. Run: npm run generate-contracts
 export const TOOLS = new Set([
     "Agent",
@@ -311,7 +311,10 @@ export const SETTINGS_USER_FIELDS = new Set([
     "worktree",
     "wslInheritsWindowsSettings",
 ]);
-export const SETTINGS_PROJECT_FIELDS = new Set([
-    "permissions",
-]);
+export const SETTINGS_PROJECT_FIELDS = new Set(["permissions"]);
+// Hand-curated denylist of tools declared in agent frontmatter that never
+// reach plugin-defined subagents at runtime. Source: tracked upstream bugs
+//   https://github.com/anthropics/claude-code/issues/52055
+//   https://github.com/anthropics/claude-code/issues/52004
+export const PLUGIN_SUBAGENT_BLOCKED_TOOLS = new Set(["Glob", "Grep"]);
 //# sourceMappingURL=contracts.js.map

package/dist/discovery.js

@@ -1,8 +1,9 @@
 import { statSync, existsSync, readFileSync } from "node:fs";
-import { basename, dirname, resolve, join } from "node:path";
+import { basename, dirname, resolve, join, relative } from "node:path";
 import { homedir } from "node:os";
 import { globSync } from "tinyglobby";
 import { minimatch } from "minimatch";
+import { CANONICAL_ARTIFACTS } from "./canonical-paths.js";
 const CLAUDE_USER_DIR = join(homedir(), ".claude");
 function loadIgnoreFile(dir) {
     const ignoreFile = join(dir, ".claudecode-lint-ignore");
@@ -172,6 +173,19 @@ function discoverInDirectory(dir) {
     for (const f of hooks) {
         artifacts.push({ filePath: f, artifactType: "hooks-json" });
     }
+    // .lsp.json (flat record at plugin root; Claude Code reads from <plugin>/.lsp.json)
+    const lspDot = join(dir, ".lsp.json");
+    if (existsSync(lspDot)) {
+        artifacts.push({ filePath: lspDot, artifactType: "lsp-json" });
+    }
+    // monitors/monitors.json
+    const monitors = globSync("monitors/monitors.json", {
+        cwd: dir,
+        absolute: true,
+    });
+    for (const f of monitors) {
+        artifacts.push({ filePath: f, artifactType: "monitors-json" });
+    }
     // Claude config files — settings
     for (const name of ["settings.json", "settings.local.json"]) {
         // Direct in dir (handles both ~/.claude/settings.json and project root)
@@ -221,8 +235,58 @@ function discoverInDirectory(dir) {
             scope: detectScope(claudeMd),
         });
     }
+    // Misplaced-file scan: only meaningful inside a plugin tree
+    // (we use `.claude-plugin/` as the marker). Outside plugin
+    // trees, a stray `plugin.json` / `hooks.json` could legitimately
+    // belong to some other tool and we don't want to false-positive.
+    if (existsSync(join(dir, ".claude-plugin"))) {
+        for (const m of findMisplacedFiles(dir)) {
+            artifacts.push(m);
+        }
+    }
     return artifacts;
 }
+/**
+ * Walk `pluginRoot` looking for files whose basename is reserved
+ * for a Claude Code artifact and which Claude Code reads only from
+ * a single canonical path. Anything matching a basename but
+ * sitting at a non-canonical location is returned as a
+ * `misplaced-file` artifact for the misplaced-file linter to flag.
+ *
+ * Ignores typical noise dirs (`node_modules`, `.git`, `dist`, the
+ * plugin install cache's `.in_use` / `.orphaned_at` markers).
+ */
+function findMisplacedFiles(pluginRoot) {
+    const out = [];
+    for (const entry of CANONICAL_ARTIFACTS) {
+        const found = globSync(`**/${entry.basename}`, {
+            cwd: pluginRoot,
+            absolute: true,
+            // dot: walk into dot-directories like `.claude-plugin/`
+            // — that's exactly where the most common misplacement
+            // (hooks.json under `.claude-plugin/` instead of plugin
+            // root's `hooks/`) lives.
+            dot: true,
+            ignore: [
+                "**/node_modules/**",
+                "**/.git/**",
+                "**/dist/**",
+                "**/.in_use/**",
+                "**/.orphaned_at/**",
+            ],
+        });
+        for (const filePath of found) {
+            const rel = relative(pluginRoot, filePath);
+            const isCanonical = entry.expectedPattern
+                ? minimatch(rel, entry.expectedPattern)
+                : rel === entry.expectedPath;
+            if (!isCanonical) {
+                out.push({ filePath, artifactType: "misplaced-file" });
+            }
+        }
+    }
+    return out;
+}
 function classifyFile(filePath) {
     const name = basename(filePath);
     const parent = basename(dirname(filePath));
@@ -232,6 +296,10 @@ function classifyFile(filePath) {
         return "skill-md";
     if (name === "hooks.json" && parent === "hooks")
         return "hooks-json";
+    if (name === ".lsp.json")
+        return "lsp-json";
+    if (name === "monitors.json" && parent === "monitors")
+        return "monitors-json";
     if (name.endsWith(".md") && parent === "agents")
         return "agent-md";
     if (name.endsWith(".md") && parent === "commands")

package/dist/index.js

@@ -2,7 +2,7 @@
 import { readFileSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
 import { resolve, relative, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import sade from "sade";
 import pc from "picocolors";
 import { loadConfig, mergeCliRules } from "./config.js";
 import { discoverArtifacts } from "./discovery.js";
@@ -16,6 +16,9 @@ import { hooksJsonLinter } from "./linters/hooks-json.js";
 import { settingsJsonLinter } from "./linters/settings-json.js";
 import { mcpJsonLinter } from "./linters/mcp-json.js";
 import { claudeMdLinter } from "./linters/claude-md.js";
+import { lspJsonLinter } from "./linters/lsp-json.js";
+import { monitorsJsonLinter } from "./linters/monitors-json.js";
+import { misplacedFileLinter, MISPLACED_FILE_RULES, } from "./linters/misplaced-file.js";
 import { pluginJsonFixer } from "./fixers/plugin-json.js";
 import { frontmatterFixer } from "./fixers/frontmatter.js";
 import { hooksJsonFixer } from "./fixers/hooks-json.js";
@@ -30,6 +33,8 @@ import { HOOKS_JSON_RULES } from "./linters/hooks-json.js";
 import { SETTINGS_JSON_RULES } from "./linters/settings-json.js";
 import { MCP_JSON_RULES } from "./linters/mcp-json.js";
 import { CLAUDE_MD_RULES } from "./linters/claude-md.js";
+import { LSP_JSON_RULES } from "./linters/lsp-json.js";
+import { MONITORS_JSON_RULES } from "./linters/monitors-json.js";
 const LINTERS = {
     "plugin-json": pluginJsonLinter,
     "skill-md": skillMdLinter,
@@ -39,6 +44,9 @@ const LINTERS = {
     "settings-json": settingsJsonLinter,
     "mcp-json": mcpJsonLinter,
     "claude-md": claudeMdLinter,
+    "lsp-json": lspJsonLinter,
+    "monitors-json": monitorsJsonLinter,
+    "misplaced-file": misplacedFileLinter,
 };
 const FIXERS = {
     "plugin-json": pluginJsonFixer,
@@ -59,6 +67,9 @@ const ALL_RULES = [
     ...SETTINGS_JSON_RULES,
     ...MCP_JSON_RULES,
     ...CLAUDE_MD_RULES,
+    ...LSP_JSON_RULES,
+    ...MONITORS_JSON_RULES,
+    ...MISPLACED_FILE_RULES,
 ];
 function simpleDiff(oldContent, newContent, filePath) {
     if (oldContent === newContent)
@@ -95,27 +106,30 @@ function simpleDiff(oldContent, newContent, filePath) {
     }
     return lines.join("\n");
 }
-const program = new Command();
-program
-    .name("claudecode-linter")
-    .description("Linter for Claude Code plugin artifacts")
-    .version(JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version)
-    .argument("[paths...]", "Plugin directories or individual files", ["."])
+const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+sade("claudecode-linter", true)
+    .version(pkgVersion)
+    .describe("Linter for Claude Code plugin artifacts")
     .option("--lint", "Lint artifacts and report issues (default)")
     .option("--fix", "Auto-fix lint violations, then report remaining issues")
     .option("--format", "Format all artifacts for consistent style (no lint output)")
-    .option("--output <type>", "Output format: human | json", "human")
-    .option("--config <path>", "Config file path")
-    .option("--scope <scope>", "Filter by scope: user | project | subdirectory")
-    .option("--ignore <patterns>", "Comma-separated glob patterns to ignore")
+    .option("--output", "Output format: human | json", "human")
+    .option("--config", "Config file path")
+    .option("--scope", "Filter by scope: user | project | subdirectory")
+    .option("--ignore", "Comma-separated glob patterns to ignore")
     .option("--quiet", "Only show errors")
-    .option("--enable <rules>", "Comma-separated rule IDs to enable")
-    .option("--disable <rules>", "Comma-separated rule IDs to disable")
-    .option("--rule <rule>", "Run only this single rule ID")
+    .option("--enable", "Comma-separated rule IDs to enable")
+    .option("--disable", "Comma-separated rule IDs to disable")
+    .option("--rule", "Run only this single rule ID")
     .option("--list-rules", "Print all rules with their default severity and exit")
     .option("--fix-dry-run", "Run fixers but print diff instead of writing")
-    .option("--init [path]", "Copy default config to path (default: current directory)")
-    .action(async (paths, opts) => {
+    .option("--init", "Copy default config to path (default: current directory)")
+    .action(async (opts) => {
+    // sade accepts variadic positional via opts._; default to ["."] when empty.
+    // Multi-word flags like --list-rules arrive in kebab-case form on opts.
+    const paths = Array.isArray(opts._) && opts._.length > 0 ? opts._ : ["."];
+    const listRules = !!opts["list-rules"];
+    const fixDryRun = !!opts["fix-dry-run"];
     try {
         if (opts.init !== undefined) {
             const __filename = fileURLToPath(import.meta.url);
@@ -131,7 +145,7 @@ program
             process.stdout.write(pc.green(`Created ${targetFile}\n`));
             process.exit(0);
         }
-        if (opts.listRules) {
+        if (listRules) {
             const sevColor = { error: pc.red, warning: pc.yellow, info: pc.blue };
             for (const rule of ALL_RULES) {
                 const color = sevColor[rule.defaultSeverity];
@@ -197,7 +211,7 @@ program
                         }
                     }
                 }
-                else if (opts.fixDryRun) {
+                else if (fixDryRun) {
                     const fixer = FIXERS[artifact.artifactType];
                     if (fixer) {
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
@@ -231,7 +245,7 @@ program
             }
             process.exit(0);
         }
-        if (!opts.fixDryRun) {
+        if (!fixDryRun) {
             const output = opts.output === "json"
                 ? formatJson(results, !!opts.quiet)
                 : formatHuman(results, !!opts.quiet);
@@ -244,6 +258,6 @@ program
         process.stderr.write(pc.red(`Fatal error: ${err.message}\n`));
         process.exit(2);
     }
-});
-program.parse();
+})
+    .parse(process.argv);
 //# sourceMappingURL=index.js.map

package/dist/linters/agent-md.js

@@ -1,6 +1,59 @@
-import { AGENT_FRONTMATTER, AGENT_MODELS, AGENT_COLORS } from "../contracts.js";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AGENT_FRONTMATTER, AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+function findPluginRoot(agentFilePath) {
+    let dir = dirname(agentFilePath);
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, ".claude-plugin", "plugin.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function loadJson(p) {
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function loadPluginName(pluginRoot) {
+    const j = loadJson(join(pluginRoot, ".claude-plugin", "plugin.json"));
+    if (j && typeof j === "object" && j !== null && "name" in j) {
+        const n = j.name;
+        return typeof n === "string" ? n : null;
+    }
+    return null;
+}
+function loadMcpServerNames(pluginRoot) {
+    const j = loadJson(join(pluginRoot, ".mcp.json"));
+    const out = new Set();
+    if (j &&
+        typeof j === "object" &&
+        j !== null &&
+        "mcpServers" in j &&
+        typeof j.mcpServers === "object" &&
+        j.mcpServers !== null) {
+        for (const k of Object.keys(j.mcpServers)) {
+            out.add(k);
+        }
+    }
+    return out;
+}
+function parseToolsField(v) {
+    if (typeof v !== "string")
+        return [];
+    return v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
 const RULES = [
     { id: "agent-md/valid-frontmatter", defaultSeverity: "error" },
     { id: "agent-md/name-required", defaultSeverity: "error" },
@@ -9,12 +62,15 @@ const RULES = [
     { id: "agent-md/description-examples", defaultSeverity: "warning" },
     { id: "agent-md/model-required", defaultSeverity: "error" },
     { id: "agent-md/model-valid", defaultSeverity: "warning" },
-    { id: "agent-md/color-required", defaultSeverity: "error" },
+    { id: "agent-md/color-required", defaultSeverity: "warning" },
     { id: "agent-md/color-valid", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
     { id: "agent-md/system-prompt-length", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-second-person", defaultSeverity: "info" },
     { id: "agent-md/no-unknown-frontmatter", defaultSeverity: "info" },
+    { id: "agent-md/known-tools", defaultSeverity: "warning" },
+    { id: "agent-md/mcp-tools-resolve", defaultSeverity: "error" },
+    { id: "agent-md/plugin-subagent-blocked-tools", defaultSeverity: "warning" },
 ];
 function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
     if (!isRuleEnabled(config, ruleId))
@@ -47,10 +103,10 @@ export const agentMdLinter = {
         }
         else {
             const name = fm.data.name;
-            if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(name) ||
-                name.length < 3 ||
+            if (!/^[a-z][a-z0-9-]*[a-z0-9]?$/.test(name) ||
+                name.length < 2 ||
                 name.length > 50) {
-                push(diag(config, filePath, "agent-md/name-format", "error", `"name" must be 3-50 chars, lowercase alphanumeric + hyphens (got "${name}")`));
+                push(diag(config, filePath, "agent-md/name-format", "error", `"name" must be 2-50 chars, lowercase alphanumeric + hyphens (got "${name}")`));
             }
         }
         // description
@@ -73,7 +129,7 @@ export const agentMdLinter = {
         }
         // color
         if (!("color" in fm.data) || typeof fm.data.color !== "string") {
-            push(diag(config, filePath, "agent-md/color-required", "error", '"color" is required in frontmatter'));
+            push(diag(config, filePath, "agent-md/color-required", "warning", '"color" is required in frontmatter'));
         }
         else if (!AGENT_COLORS.has(fm.data.color)) {
             push(diag(config, filePath, "agent-md/color-valid", "warning", `"color" must be one of: ${[...AGENT_COLORS].join(", ")} (got "${fm.data.color}")`));
@@ -98,6 +154,50 @@ export const agentMdLinter = {
                 push(diag(config, filePath, "agent-md/system-prompt-second-person", "info", 'System prompt should use second person ("You are...", "You will...")', fm.bodyStartLine));
             }
         }
+        // tools
+        const declaredTools = parseToolsField(fm.data.tools);
+        if (declaredTools.length > 0) {
+            const pluginRoot = findPluginRoot(filePath);
+            const pluginName = pluginRoot ? loadPluginName(pluginRoot) : null;
+            const mcpServers = pluginRoot
+                ? loadMcpServerNames(pluginRoot)
+                : new Set();
+            for (const t of declaredTools) {
+                if (t.startsWith("mcp__")) {
+                    // Two valid shapes:
+                    //   mcp__plugin_<plugin>_<server>__<tool>   plugin-namespaced
+                    //   mcp__<server>__<tool>                   user-config (non-plugin)
+                    const ns = t.match(/^mcp__plugin_([a-z0-9-]+)_([a-z0-9-]+)__(.+)$/);
+                    const bare = t.match(/^mcp__([a-z0-9-]+)__(.+)$/);
+                    if (ns) {
+                        const declaredPlugin = ns[1];
+                        const declaredServer = ns[2];
+                        if (pluginName && declaredPlugin !== pluginName) {
+                            push(diag(config, filePath, "agent-md/mcp-tools-resolve", "error", `Tool "${t}" references plugin "${declaredPlugin}", but this plugin is named "${pluginName}".`));
+                        }
+                        if (pluginRoot &&
+                            mcpServers.size > 0 &&
+                            !mcpServers.has(declaredServer)) {
+                            push(diag(config, filePath, "agent-md/mcp-tools-resolve", "error", `Tool "${t}" references MCP server "${declaredServer}", but .mcp.json declares: [${[...mcpServers].join(", ")}].`));
+                        }
+                    }
+                    else if (bare && pluginRoot) {
+                        const server = bare[1];
+                        const rest = bare[2];
+                        if (mcpServers.has(server)) {
+                            push(diag(config, filePath, "agent-md/mcp-tools-resolve", "error", `Tool "${t}" uses bare "mcp__<server>__<tool>" form, but this is a plugin (${pluginName ?? "unknown name"}). Plugin agents must use the namespaced form: "mcp__plugin_${pluginName ?? "<plugin>"}_${server}__${rest}".`));
+                        }
+                    }
+                    continue;
+                }
+                if (!TOOLS.has(t)) {
+                    push(diag(config, filePath, "agent-md/known-tools", "warning", `Unknown built-in tool "${t}" in tools: field. Valid: ${[...TOOLS].sort().join(", ")}.`));
+                }
+                if (pluginRoot && PLUGIN_SUBAGENT_BLOCKED_TOOLS.has(t)) {
+                    push(diag(config, filePath, "agent-md/plugin-subagent-blocked-tools", "warning", `Tool "${t}" is declared but does NOT reach plugin subagents at runtime — known Claude Code bug (https://github.com/anthropics/claude-code/issues/52055). The agent will silently lack this tool. For local file ops, use Bash with rg/find, or dispatch the built-in Explore subagent.`));
+                }
+            }
+        }
         return diagnostics;
     },
 };

package/dist/linters/lsp-json.js

@@ -0,0 +1,94 @@
+/**
+ * Lints standalone `.lsp.json` files (a flat map of server-name → LSP server
+ * config). Validates against the schema auto-extracted from Claude Code's
+ * runtime parser `E.record(E.string(), RSH()).safeParse(content)` — see
+ * scripts/extract-plugin-schema.ts → buildLspSchema().
+ *
+ * The most common mistake (observed in cluster plugin 0.29.0 → 0.30.3) is
+ * wrapping the contents under a top-level `lspServers` key. That wrapper only
+ * belongs inside plugin.json; a dedicated `.lsp.json` file must be flat.
+ * lsp-json/no-lsp-servers-wrapper catches this with a friendlier message
+ * than the generic "missing required field command" Ajv would otherwise emit.
+ */
+import { formatAjvError, loadLspSchema, summarizeErrors, } from "../plugin-schema.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+const RULES = [
+    { id: "lsp-json/valid-json", defaultSeverity: "error" },
+    { id: "lsp-json/no-lsp-servers-wrapper", defaultSeverity: "error" },
+    { id: "lsp-json/schema-valid", defaultSeverity: "error" },
+];
+function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
+    if (!isRuleEnabled(config, ruleId))
+        return null;
+    return {
+        rule: ruleId,
+        severity: getRuleSeverity(config, ruleId, defaultSeverity),
+        message,
+        file: filePath,
+        line,
+        column,
+    };
+}
+function findKeyPosition(content, key) {
+    const re = new RegExp(`"${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\s*:`);
+    const match = re.exec(content);
+    if (!match)
+        return undefined;
+    const before = content.slice(0, match.index);
+    const line = before.split("\n").length;
+    const lastNl = before.lastIndexOf("\n");
+    const column = match.index - lastNl;
+    return { line, column };
+}
+export const lspJsonLinter = {
+    artifactType: "lsp-json",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => {
+            if (d)
+                diagnostics.push(d);
+        };
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "lsp-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            push(diag(config, filePath, "lsp-json/valid-json", "error", ".lsp.json must be a JSON object (map of server-name → config)"));
+            return diagnostics;
+        }
+        const obj = parsed;
+        // Special-case the cluster-plugin bug: wrapping content under "lspServers".
+        // That key is only valid inline in plugin.json. The dedicated file uses a
+        // flat map, so an "lspServers" wrapper is silently mis-validated by Claude
+        // Code at session start (each server entry fails RSH validation since it
+        // looks like one server config with sub-server keys).
+        if ("lspServers" in obj) {
+            const p = findKeyPosition(content, "lspServers");
+            push(diag(config, filePath, "lsp-json/no-lsp-servers-wrapper", "error", '.lsp.json must not have a top-level "lspServers" key — the file is itself the map of server-name → config. The "lspServers" wrapper only belongs in plugin.json under the lspServers field.', p?.line, p?.column));
+        }
+        // Schema validation — defers to the extracted Zod-equivalent JSON Schema.
+        if (isRuleEnabled(config, "lsp-json/schema-valid")) {
+            const ctx = loadLspSchema();
+            if (ctx) {
+                const ok = ctx.validate(parsed);
+                if (!ok && ctx.validate.errors) {
+                    const filtered = summarizeErrors(ctx.validate.errors);
+                    for (const err of filtered) {
+                        const firstSeg = err.instancePath
+                            .split("/")
+                            .filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "lsp-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as LSP_JSON_RULES };
+//# sourceMappingURL=lsp-json.js.map

package/dist/linters/misplaced-file.js

@@ -0,0 +1,45 @@
+import { basename } from "node:path";
+import { CANONICAL_ARTIFACTS } from "../canonical-paths.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+export const MISPLACED_FILE_RULES = [
+    { id: "misplaced-file/canonical-location", defaultSeverity: "warning" },
+];
+/**
+ * Flag files whose basename is reserved for a Claude Code artifact
+ * but which sit at a non-canonical path. Claude Code reads each
+ * artifact only from its canonical location and silently ignores
+ * copies elsewhere, so this class of mistake is easy to make and
+ * hard to debug — `/reload-plugins` reports `0 hooks` (or skills,
+ * etc.) with no other signal.
+ *
+ * Discovery (see discovery.ts) populates this linter's inputs by
+ * walking plugin trees and matching basenames; this linter just
+ * emits one diagnostic per misplaced file with the expected
+ * location.
+ */
+export const misplacedFileLinter = {
+    artifactType: "misplaced-file",
+    lint(filePath, _content, config) {
+        const ruleId = "misplaced-file/canonical-location";
+        if (!isRuleEnabled(config, ruleId))
+            return [];
+        const base = basename(filePath);
+        const entry = CANONICAL_ARTIFACTS.find((a) => a.basename === base);
+        if (!entry)
+            return [];
+        const expected = entry.expectedPath ?? entry.expectedPattern ?? "";
+        return [
+            {
+                rule: ruleId,
+                severity: getRuleSeverity(config, ruleId, "warning"),
+                message: `${base} is at a non-canonical path; ` +
+                    `Claude Code reads ${entry.description} only from ` +
+                    `\`${expected}\` (relative to plugin root) and ` +
+                    `silently ignores copies elsewhere. ` +
+                    `Move the file there or rename it.`,
+                file: filePath,
+            },
+        ];
+    },
+};
+//# sourceMappingURL=misplaced-file.js.map

package/dist/linters/monitors-json.js

@@ -0,0 +1,85 @@
+/**
+ * Lints standalone `monitors/monitors.json` files (an array of monitor
+ * entries). Validates against the schema auto-extracted from Claude Code's
+ * runtime parser `vC8().parse(content)` — see scripts/extract-plugin-schema.ts
+ * → buildMonitorsSchema().
+ *
+ * monitors-json/unique-names mirrors Claude Code's refine() check that
+ * `Monitor names must be unique within a plugin`. JSON Schema can't express
+ * that constraint natively so we enforce it here.
+ */
+import { formatAjvError, loadMonitorsSchema, summarizeErrors, } from "../plugin-schema.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+const RULES = [
+    { id: "monitors-json/valid-json", defaultSeverity: "error" },
+    { id: "monitors-json/schema-valid", defaultSeverity: "error" },
+    { id: "monitors-json/unique-names", defaultSeverity: "error" },
+];
+function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
+    if (!isRuleEnabled(config, ruleId))
+        return null;
+    return {
+        rule: ruleId,
+        severity: getRuleSeverity(config, ruleId, defaultSeverity),
+        message,
+        file: filePath,
+        line,
+        column,
+    };
+}
+export const monitorsJsonLinter = {
+    artifactType: "monitors-json",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => {
+            if (d)
+                diagnostics.push(d);
+        };
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "monitors-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (!Array.isArray(parsed)) {
+            push(diag(config, filePath, "monitors-json/valid-json", "error", "monitors.json must be a JSON array of monitor entries"));
+            return diagnostics;
+        }
+        // Schema validation
+        if (isRuleEnabled(config, "monitors-json/schema-valid")) {
+            const ctx = loadMonitorsSchema();
+            if (ctx) {
+                const ok = ctx.validate(parsed);
+                if (!ok && ctx.validate.errors) {
+                    const filtered = summarizeErrors(ctx.validate.errors);
+                    for (const err of filtered) {
+                        push(diag(config, filePath, "monitors-json/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
+        // Unique-name refinement — Claude Code's refine() check.
+        if (isRuleEnabled(config, "monitors-json/unique-names")) {
+            const seen = new Set();
+            const duplicates = new Set();
+            for (const entry of parsed) {
+                if (entry &&
+                    typeof entry === "object" &&
+                    typeof entry.name === "string") {
+                    const name = entry.name;
+                    if (seen.has(name))
+                        duplicates.add(name);
+                    seen.add(name);
+                }
+            }
+            for (const dup of duplicates) {
+                push(diag(config, filePath, "monitors-json/unique-names", "error", `Monitor name "${dup}" is duplicated. Monitor names must be unique within a plugin.`));
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as MONITORS_JSON_RULES };
+//# sourceMappingURL=monitors-json.js.map