@onlooker-community/ecosystem 0.9.0 → 0.14.0

package/scripts/lib/validate-path.sh

@@ -22,6 +22,10 @@ export ONLOOKER_EVENTS_LOG="$ONLOOKER_DIR/logs/onlooker-events.jsonl"
 export ONLOOKER_HOOK_HEALTH_LOG="$ONLOOKER_DIR/logs/hook-health.jsonl"
 _VALIDATE_PATH_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 export ONLOOKER_EMIT="$_VALIDATE_PATH_DIR/onlooker-emit.sh"
+# Portable mutex (flock substitute) — every hook script that needs to write
+# shared state can call lock_acquire/lock_release after sourcing this file.
+# shellcheck source=portable-lock.sh
+source "$_VALIDATE_PATH_DIR/portable-lock.sh"
 unset _VALIDATE_PATH_DIR
 
 # ==============================================================================

package/scripts/lint/check-manifests.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// Manifest validator for the Onlooker marketplace.
+//
+// Asserts that .claude-plugin/marketplace.json and every plugin's
+// .claude-plugin/plugin.json match the Claude Code plugin schema, and that
+// our own conventions hold:
+//
+//   * marketplace.json plugins[] entries MUST NOT carry a `version` field
+//     (the drift trap — plugin.json's version silently wins at runtime, so
+//     setting both is documented as harmful in plugins-reference).
+//   * plugin.json `name` matches its marketplace entry name (no surprise
+//     renames).
+//   * plugin.json `name` is kebab-case (matches plugin loader conventions).
+//   * plugin.json `version` is semver-shaped.
+//   * resource arrays (skills/commands/agents) and mcpServers/hooks fields
+//     have the expected types.
+//
+// Exit codes:
+//   0  ok
+//   1  one or more schema violations
+//   2  setup/usage error
+//
+// Flags:
+//   --strict             treat warnings (unknown fields, missing optional
+//                        recommended fields) as errors
+//   --root <path>        override the repo root
+//   --plugin <name>      only validate the named plugin (repeatable)
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const KEBAB_CASE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+// Fields we recognize on each manifest. Unknown fields trigger a warning
+// (typo detection). New fields should be added here as Claude Code's schema
+// evolves.
+const KNOWN_MARKETPLACE_FIELDS = new Set(['name', 'owner', 'metadata', 'plugins', '$schema']);
+const KNOWN_MARKETPLACE_PLUGIN_FIELDS = new Set([
+  'name',
+  'source',
+  'description',
+  'author',
+  'homepage',
+  'repository',
+  'license',
+  'keywords',
+  'tags',
+]);
+const KNOWN_PLUGIN_JSON_FIELDS = new Set([
+  'name',
+  'version',
+  'description',
+  'author',
+  'homepage',
+  'repository',
+  'license',
+  'skills',
+  'commands',
+  'agents',
+  'mcpServers',
+  'hooks',
+  'keywords',
+  '$schema',
+]);
+const KNOWN_HOOK_EVENTS = new Set([
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'PermissionRequest',
+  'PermissionDenied',
+  'SessionStart',
+  'SessionEnd',
+  'Notification',
+  'SubagentStart',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStop',
+  'ConfigChange',
+  'CwdChanged',
+  'FileChanged',
+  'StopFailure',
+  'InstructionsLoaded',
+  'Elicitation',
+  'ElicitationResult',
+  'UserPromptSubmit',
+  'UserPromptExpansion',
+  'Stop',
+  'TeammateIdle',
+  'TaskCreated',
+  'TaskCompleted',
+  'WorktreeCreate',
+  'WorktreeRemove',
+]);
+
+function findRepoRoot(start) {
+  let cur = resolve(start);
+  while (cur !== '/') {
+    if (existsSync(join(cur, '.claude-plugin', 'marketplace.json'))) return cur;
+    cur = dirname(cur);
+  }
+  throw new Error(`could not find .claude-plugin/marketplace.json above ${start}`);
+}
+
+function parseArgs(argv) {
+  const out = { strict: false, plugins: [], root: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--strict') out.strict = true;
+    else if (a === '--plugin') out.plugins.push(argv[++i]);
+    else if (a === '--root') out.root = argv[++i];
+    else if (a === '-h' || a === '--help') {
+      process.stderr.write('Usage: check-manifests.mjs [--strict] [--plugin name]... [--root path]\n');
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function readJson(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    return { __readError: `cannot read ${label} at ${path}: ${err.message}` };
+  }
+}
+
+function validateMarketplace(marketplace, errors, warnings) {
+  if (!isPlainObject(marketplace)) {
+    errors.push('marketplace.json must be a JSON object');
+    return;
+  }
+  if (typeof marketplace.name !== 'string' || marketplace.name.length === 0) {
+    errors.push('marketplace.json: `name` is required and must be a non-empty string');
+  }
+  if (!Array.isArray(marketplace.plugins)) {
+    errors.push('marketplace.json: `plugins` is required and must be an array');
+  }
+  if (marketplace.owner !== undefined && !isPlainObject(marketplace.owner)) {
+    errors.push('marketplace.json: `owner` must be an object when present');
+  }
+  if (marketplace.owner && typeof marketplace.owner.name !== 'string') {
+    errors.push('marketplace.json: `owner.name` is required when `owner` is present');
+  }
+  for (const key of Object.keys(marketplace)) {
+    if (!KNOWN_MARKETPLACE_FIELDS.has(key)) {
+      warnings.push(`marketplace.json: unknown top-level field "${key}"`);
+    }
+  }
+}
+
+function validateMarketplacePluginEntry(entry, index, errors, warnings) {
+  const label = `marketplace.json plugins[${index}]`;
+  if (!isPlainObject(entry)) {
+    errors.push(`${label}: must be an object`);
+    return;
+  }
+  if (typeof entry.name !== 'string' || !KEBAB_CASE.test(entry.name)) {
+    errors.push(`${label}: \`name\` is required and must be kebab-case (got ${JSON.stringify(entry.name)})`);
+  }
+  if (typeof entry.source !== 'string' || entry.source.length === 0) {
+    errors.push(`${label}: \`source\` is required and must be a string`);
+  }
+  if ('version' in entry) {
+    errors.push(
+      `${label}: \`version\` MUST NOT be set in marketplace.json — Claude Code reads version from each plugin's own plugin.json, and setting both is a documented drift hazard.`,
+    );
+  }
+  for (const key of Object.keys(entry)) {
+    if (!KNOWN_MARKETPLACE_PLUGIN_FIELDS.has(key)) {
+      warnings.push(`${label}: unknown field "${key}"`);
+    }
+  }
+}
+
+function validatePluginJson(pluginJson, marketplaceName, label, errors, warnings) {
+  if (!isPlainObject(pluginJson)) {
+    errors.push(`${label}: plugin.json must be a JSON object`);
+    return;
+  }
+  if (typeof pluginJson.name !== 'string' || !KEBAB_CASE.test(pluginJson.name)) {
+    errors.push(`${label}: \`name\` is required and must be kebab-case (got ${JSON.stringify(pluginJson.name)})`);
+  } else if (pluginJson.name !== marketplaceName) {
+    errors.push(
+      `${label}: plugin.json \`name\` "${pluginJson.name}" does not match marketplace entry name "${marketplaceName}"`,
+    );
+  }
+  if (typeof pluginJson.version !== 'string' || pluginJson.version.length === 0) {
+    errors.push(`${label}: \`version\` is required and must be a non-empty string`);
+  } else if (!SEMVER.test(pluginJson.version)) {
+    errors.push(`${label}: \`version\` is not semver-shaped (got ${JSON.stringify(pluginJson.version)})`);
+  }
+  if (typeof pluginJson.description !== 'string' || pluginJson.description.length === 0) {
+    errors.push(`${label}: \`description\` is required and must be a non-empty string`);
+  }
+  for (const field of ['skills', 'commands', 'agents']) {
+    if (pluginJson[field] !== undefined && !Array.isArray(pluginJson[field])) {
+      errors.push(`${label}: \`${field}\` must be an array when present`);
+    }
+  }
+  if (pluginJson.mcpServers !== undefined && !isPlainObject(pluginJson.mcpServers)) {
+    errors.push(`${label}: \`mcpServers\` must be an object when present`);
+  }
+  for (const key of Object.keys(pluginJson)) {
+    if (!KNOWN_PLUGIN_JSON_FIELDS.has(key)) {
+      warnings.push(`${label}: unknown field "${key}"`);
+    }
+  }
+}
+
+function validateHooksJson(hooksJson, label, errors, warnings) {
+  if (!isPlainObject(hooksJson)) {
+    errors.push(`${label}: hooks.json must be a JSON object`);
+    return;
+  }
+  if (!isPlainObject(hooksJson.hooks)) {
+    errors.push(`${label}: hooks.json must contain a \`hooks\` object`);
+    return;
+  }
+  for (const [event, value] of Object.entries(hooksJson.hooks)) {
+    if (!KNOWN_HOOK_EVENTS.has(event)) {
+      warnings.push(`${label}: hooks.json declares unknown event "${event}"`);
+    }
+    if (!Array.isArray(value)) {
+      errors.push(`${label}: hooks.json event "${event}" must be an array`);
+      continue;
+    }
+    for (let i = 0; i < value.length; i++) {
+      const matcher = value[i];
+      if (!isPlainObject(matcher)) {
+        errors.push(`${label}: hooks.json ${event}[${i}] must be an object`);
+        continue;
+      }
+      if (!Array.isArray(matcher.hooks)) {
+        errors.push(`${label}: hooks.json ${event}[${i}].hooks must be an array`);
+      }
+    }
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = args.root ? resolve(args.root) : findRepoRoot(here);
+
+  const marketplacePath = join(root, '.claude-plugin', 'marketplace.json');
+  const marketplace = readJson(marketplacePath, 'marketplace.json');
+  if (marketplace.__readError) {
+    process.stderr.write(`error: ${marketplace.__readError}\n`);
+    process.exit(2);
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  validateMarketplace(marketplace, errors, warnings);
+
+  const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+  const filter = args.plugins.length === 0 ? null : new Set(args.plugins);
+
+  for (let i = 0; i < plugins.length; i++) {
+    const entry = plugins[i];
+    validateMarketplacePluginEntry(entry, i, errors, warnings);
+    if (!isPlainObject(entry) || typeof entry.name !== 'string' || typeof entry.source !== 'string') {
+      continue;
+    }
+    if (filter && !filter.has(entry.name)) continue;
+
+    const pluginRoot = resolve(root, entry.source);
+    const pluginJsonPath = join(pluginRoot, '.claude-plugin', 'plugin.json');
+    const label = `plugin "${entry.name}"`;
+    const pluginJson = readJson(pluginJsonPath, `${label} plugin.json`);
+    if (pluginJson.__readError) {
+      errors.push(pluginJson.__readError);
+      continue;
+    }
+    validatePluginJson(pluginJson, entry.name, label, errors, warnings);
+
+    // Validate hooks/hooks.json if the plugin appears to ship hooks.
+    const hooksJsonPath = join(pluginRoot, 'hooks', 'hooks.json');
+    if (existsSync(hooksJsonPath)) {
+      const stat = statSync(hooksJsonPath);
+      if (stat.isFile()) {
+        const hooksJson = readJson(hooksJsonPath, `${label} hooks.json`);
+        if (hooksJson.__readError) {
+          errors.push(hooksJson.__readError);
+        } else {
+          validateHooksJson(hooksJson, `${label} (${relative(root, hooksJsonPath)})`, errors, warnings);
+        }
+      }
+    }
+  }
+
+  for (const e of errors) process.stderr.write(`error: ${e}\n`);
+  for (const w of warnings) process.stderr.write(`warn:  ${w}\n`);
+
+  const failing = errors.length > 0 || (args.strict && warnings.length > 0);
+  if (failing) {
+    process.stderr.write(`check-manifests: ${errors.length} error(s), ${warnings.length} warning(s)\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`check-manifests: ok (${plugins.length} plugin(s), ${warnings.length} warning(s))\n`);
+}
+
+main();

package/scripts/lint/check-references.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+// Cross-reference linter for the Onlooker marketplace.
+//
+// Walks every plugin declared in `.claude-plugin/marketplace.json` and:
+//   1. asserts every path under plugin.json's `skills`, `commands`, `agents`,
+//      and `hooks` fields resolves to a real file or directory inside the
+//      plugin's source tree;
+//   2. parses YAML frontmatter from each markdown skill/command/agent and
+//      asserts the required fields (`name`, `description`) are present;
+//   3. builds a cross-marketplace registry of declared commands/skills/agents
+//      and scans every markdown body for slash-command references
+//      (`/foo`) — anything that is not a known built-in or a declared
+//      command is reported as a warning.
+//
+// Exit codes:
+//   0  no problems
+//   1  at least one error (broken path or invalid frontmatter)
+//   2  setup/usage error
+//
+// Flags:
+//   --strict             treat warnings as errors
+//   --plugin <name>      only check the named plugin (repeatable)
+//   --root <path>        override the repo root (defaults to git toplevel)
+//   --print-registry     dump the resolved registry to stderr (debugging)
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Slash commands shipped by Claude Code itself. References to these never
+// fail; they are valid even though we cannot resolve them in the
+// marketplace. Kept short on purpose — additions should be deliberate.
+const BUILTIN_COMMANDS = new Set([
+  'clear',
+  'compact',
+  'config',
+  'help',
+  'loop',
+  'plugin',
+  'reload-plugins',
+  'effort',
+  'commit',
+  'fast',
+]);
+
+// Required frontmatter fields per resource kind. Skills/commands/agents all
+// need at least name+description; everything else is optional metadata.
+const REQUIRED_FRONTMATTER = ['name', 'description'];
+
+function findRepoRoot(start) {
+  let cur = resolve(start);
+  while (cur !== '/') {
+    try {
+      statSync(join(cur, '.claude-plugin', 'marketplace.json'));
+      return cur;
+    } catch {}
+    cur = dirname(cur);
+  }
+  throw new Error(`could not find .claude-plugin/marketplace.json above ${start}`);
+}
+
+function parseArgs(argv) {
+  const out = { strict: false, plugins: [], printRegistry: false, root: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--strict') out.strict = true;
+    else if (a === '--print-registry') out.printRegistry = true;
+    else if (a === '--plugin') out.plugins.push(argv[++i]);
+    else if (a === '--root') out.root = argv[++i];
+    else if (a === '-h' || a === '--help') {
+      process.stderr.write(
+        'Usage: check-references.mjs [--strict] [--plugin name]... [--root path] [--print-registry]\n',
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+// Minimal YAML frontmatter parser. We only need `key: value` and quoted
+// strings — no nesting, no lists. Sufficient for plugin resource frontmatter,
+// and avoids pulling in a YAML dependency.
+function parseFrontmatter(source) {
+  const lines = source.split(/\r?\n/);
+  if (lines[0] !== '---') return { frontmatter: null, body: source };
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) return { frontmatter: null, body: source };
+  const fm = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!m) continue;
+    let v = m[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    fm[m[1]] = v;
+  }
+  return { frontmatter: fm, body: lines.slice(end + 1).join('\n') };
+}
+
+// Resolve a plugin manifest entry that may be either a bare string or
+// `{ source, name? }` to an absolute path inside the plugin tree.
+function entryPath(pluginRoot, entry) {
+  if (typeof entry === 'string') return resolve(pluginRoot, entry);
+  if (entry && typeof entry === 'object' && typeof entry.source === 'string') {
+    return resolve(pluginRoot, entry.source);
+  }
+  return null;
+}
+
+// Extract a friendly identifier from an entry for error messages.
+function entryLabel(entry) {
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object') {
+    return entry.name ?? entry.source ?? JSON.stringify(entry);
+  }
+  return String(entry);
+}
+
+// Walk a single resource kind (skills/commands/agents) for a plugin.
+// Returns { errors[], records[] } where records are { kind, name, file, plugin }.
+function checkResourceKind(plugin, pluginJson, kind, pluginRoot) {
+  const errors = [];
+  const records = [];
+  const entries = pluginJson[kind];
+  if (!Array.isArray(entries)) return { errors, records };
+
+  for (const entry of entries) {
+    const abs = entryPath(pluginRoot, entry);
+    if (!abs) {
+      errors.push(`[${plugin}] ${kind} entry has neither a string path nor a {source} field: ${entryLabel(entry)}`);
+      continue;
+    }
+
+    let stat;
+    try {
+      stat = statSync(abs);
+    } catch {
+      errors.push(`[${plugin}] ${kind} entry points to a missing file: ${entryLabel(entry)} (${abs})`);
+      continue;
+    }
+
+    // If it's a directory, look for either SKILL.md / COMMAND.md / AGENT.md
+    // or any single .md file inside. We treat each found .md as one record.
+    const files = stat.isDirectory() ? collectMarkdownInDir(abs) : [abs];
+    if (files.length === 0) {
+      errors.push(`[${plugin}] ${kind} entry directory contains no markdown: ${abs}`);
+      continue;
+    }
+
+    for (const file of files) {
+      const raw = readFileSync(file, 'utf8');
+      const { frontmatter } = parseFrontmatter(raw);
+      if (!frontmatter) {
+        errors.push(`[${plugin}] ${kind} file is missing YAML frontmatter: ${relative(pluginRoot, file)}`);
+        continue;
+      }
+      for (const required of REQUIRED_FRONTMATTER) {
+        if (!frontmatter[required] || frontmatter[required].trim() === '') {
+          errors.push(
+            `[${plugin}] ${kind} file is missing required frontmatter field "${required}": ${relative(pluginRoot, file)}`,
+          );
+        }
+      }
+      records.push({
+        kind,
+        plugin,
+        name: frontmatter.name ?? entryLabel(entry),
+        file,
+      });
+    }
+  }
+
+  return { errors, records };
+}
+
+function collectMarkdownInDir(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let items;
+    try {
+      items = readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const item of items) {
+      const p = join(cur, item.name);
+      if (item.isDirectory()) stack.push(p);
+      else if (item.isFile() && p.toLowerCase().endsWith('.md')) out.push(p);
+    }
+  }
+  return out.sort();
+}
+
+// Scan a markdown body for slash-command references. Returns an array of
+// `{ name, line }` for everything that looks like a slash command.
+function findSlashCommands(body) {
+  const refs = [];
+  const lines = body.split(/\r?\n/);
+  // A slash command is /name where name is lowercase + digits + hyphen.
+  // We require a non-word char (or start-of-string) before the `/` so URLs,
+  // regex literals, and option flags don't match.
+  const rx = /(^|[\s(`'"])\/([a-z][a-z0-9-]{1,40})\b/g;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Skip fenced code blocks and inline code: an exhaustive parser is
+    // overkill, but we strip backtick-enclosed runs first to cut down on
+    // the most common false positives.
+    const stripped = line.replace(/`[^`]*`/g, '');
+    rx.lastIndex = 0;
+    let m = rx.exec(stripped);
+    while (m !== null) {
+      refs.push({ name: m[2], line: i + 1 });
+      m = rx.exec(stripped);
+    }
+  }
+  return refs;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = args.root ? resolve(args.root) : findRepoRoot(here);
+
+  const marketplacePath = join(root, '.claude-plugin', 'marketplace.json');
+  let marketplace;
+  try {
+    marketplace = JSON.parse(readFileSync(marketplacePath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`could not read ${marketplacePath}: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const plugins = (marketplace.plugins ?? []).filter((p) => args.plugins.length === 0 || args.plugins.includes(p.name));
+  if (plugins.length === 0) {
+    process.stderr.write('no plugins matched\n');
+    process.exit(2);
+  }
+
+  const errors = [];
+  const warnings = [];
+  const allRecords = [];
+  const commandRegistry = new Set(BUILTIN_COMMANDS);
+
+  for (const plugin of plugins) {
+    const pluginRoot = resolve(root, plugin.source ?? '.');
+    const pluginJsonPath = join(pluginRoot, '.claude-plugin', 'plugin.json');
+    let pluginJson;
+    try {
+      pluginJson = JSON.parse(readFileSync(pluginJsonPath, 'utf8'));
+    } catch (err) {
+      errors.push(`[${plugin.name}] cannot read plugin.json: ${err.message}`);
+      continue;
+    }
+
+    for (const kind of ['skills', 'commands', 'agents']) {
+      const { errors: kindErrors, records } = checkResourceKind(plugin.name, pluginJson, kind, pluginRoot);
+      errors.push(...kindErrors);
+      allRecords.push(...records);
+      if (kind === 'commands') {
+        for (const rec of records) commandRegistry.add(rec.name);
+      }
+    }
+  }
+
+  // Pass 2: cross-reference body slash commands.
+  for (const rec of allRecords) {
+    const raw = readFileSync(rec.file, 'utf8');
+    const { body } = parseFrontmatter(raw);
+    const refs = findSlashCommands(body ?? raw);
+    for (const r of refs) {
+      if (!commandRegistry.has(r.name)) {
+        warnings.push(
+          `[${rec.plugin}] ${rec.kind}/${rec.name} references unknown command "/${r.name}" at line ${r.line} of ${relative(root, rec.file)}`,
+        );
+      }
+    }
+  }
+
+  if (args.printRegistry) {
+    process.stderr.write(`registry: ${JSON.stringify([...commandRegistry].sort())}\n`);
+    process.stderr.write(`records:\n`);
+    for (const r of allRecords) {
+      process.stderr.write(`  [${r.plugin}] ${r.kind}/${r.name} -> ${relative(root, r.file)}\n`);
+    }
+  }
+
+  for (const e of errors) process.stderr.write(`error: ${e}\n`);
+  for (const w of warnings) process.stderr.write(`warn:  ${w}\n`);
+
+  const failing = errors.length > 0 || (args.strict && warnings.length > 0);
+  if (failing) {
+    process.stderr.write(`check-references: ${errors.length} error(s), ${warnings.length} warning(s)\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`check-references: ok (${allRecords.length} records, ${warnings.length} warning(s))\n`);
+}
+
+main();

package/skills/list-prompt-rules/SKILL.md

@@ -0,0 +1,15 @@
+---
+description: List all prompt rules (global + project) with their pattern, guidance, and per-session fire status. Use when asked which prompt rules are active, why a rule did or didn't fire, or to debug the prompt-rule-injector hook.
+disable-model-invocation: true
+allowed-tools: Bash(bash *)
+---
+
+# List prompt rules
+
+```!
+bash -c '
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/validate-path.sh"
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/prompt-rules.sh"
+prompt_rules_list_table "${CLAUDE_SESSION_ID}" "$(pwd)"
+'
+```