@ketecode/loom 0.0.0-stage → 0.2.0

package/scripts/lib/hooks-install.js

@@ -0,0 +1,294 @@
+'use strict';
+
+// Registers kete-loom hooks with each host (verified against host docs and Kete Code's source,
+// Oct 2026). User scope only. Every host calls `"<node>" "~/.kete-loom/hooks/run.js" <host> <hook>
+// <event>`; that command string is how we recognise our own entries, so we never touch anyone else's.
+//
+// Shared settings files (Claude Code, Gemini CLI, Kete Code) are edited in place: parsed as strict
+// JSON, backed up to `<file>.kete-loom-backup`, written atomically, and refused (with a snippet to
+// paste) when they contain comments, since rewriting would drop them.
+
+const fs = require('fs');
+const path = require('path');
+
+const RUNNER_RE = /\.kete-loom[\\/]hooks[\\/]run\.js"?\s+([a-z]+)\s+([a-z0-9-]+)(?:\s+([a-z-]+))?\s*$/;
+// Seconds. A formatter run after an edit gets longer than a check before one.
+const TIMEOUT_S = { 'pre-shell': 10, 'pre-edit': 10, 'post-edit': 60, 'session-start': 10, stop: 10, 'stop-gate': 180 };
+
+const runtimeDir = (home) => path.join(home, '.kete-loom', 'hooks');
+const command = (home, host, hook, event = 'pre-shell', node = process.execPath) =>
+  `"${node}" "${path.join(runtimeDir(home), 'run.js')}" ${host} ${hook} ${event}`;
+
+function ours(cmd, hook) {
+  const m = typeof cmd === 'string' && RUNNER_RE.exec(cmd);
+  return Boolean(m) && (!hook || m[2] === hook);
+}
+
+// Host event name and tool matcher for each kete-loom event; a missing entry means the host can't
+// run that event (Cursor has no documented pre-edit hook; OpenCode can't add context at session start).
+// stop-gate needs a stop hook that can make the agent continue: Kete Code's Stop can only notify, and
+// OpenCode's session.idle can't do either from a command.
+const EVENTS = {
+  claude: { 'pre-shell': ['PreToolUse', 'Bash'], 'pre-edit': ['PreToolUse', 'Edit|Write|NotebookEdit'], 'post-edit': ['PostToolUse', 'Edit|Write|NotebookEdit'], 'session-start': ['SessionStart'], stop: ['Stop'], 'stop-gate': ['Stop'] },
+  codex: { 'pre-shell': ['PreToolUse', 'Bash'], 'pre-edit': ['PreToolUse', 'apply_patch'], 'post-edit': ['PostToolUse', 'apply_patch'], 'session-start': ['SessionStart'], stop: ['Stop'], 'stop-gate': ['Stop'] },
+  gemini: { 'pre-shell': ['BeforeTool', 'run_shell_command'], 'pre-edit': ['BeforeTool', 'write_file|replace'], 'post-edit': ['AfterTool', 'write_file|replace'], 'session-start': ['SessionStart'], stop: ['AfterAgent'], 'stop-gate': ['AfterAgent'] },
+  kete: { 'pre-shell': ['PreToolUse', 'shell'], 'pre-edit': ['PreToolUse', 'edit|write|patch'], 'post-edit': ['PostToolUse', 'edit|write|patch'], 'session-start': ['SessionStart'], stop: ['Stop'] },
+  cursor: { 'pre-shell': ['beforeShellExecution'], 'post-edit': ['afterFileEdit'], 'session-start': ['sessionStart'], stop: ['stop'], 'stop-gate': ['stop'] },
+  copilot: { 'pre-shell': ['preToolUse'], 'pre-edit': ['preToolUse'], 'post-edit': ['postToolUse'], 'session-start': ['sessionStart'], stop: ['agentStop'], 'stop-gate': ['agentStop'] },
+  opencode: { 'pre-shell': ['tool.execute.before'], 'pre-edit': ['tool.execute.before'], 'post-edit': ['tool.execute.after'] },
+};
+
+// Claude-style `{ <event>: [{ matcher, hooks: [entry] }] }` (Claude Code, Codex, Gemini CLI).
+function removeGrouped(map, hook) {
+  let removed = 0;
+  for (const ev of Object.keys(map || {})) {
+    if (!Array.isArray(map[ev])) continue;
+    map[ev] = map[ev].filter((group) => {
+      if (!group || !Array.isArray(group.hooks)) return true;
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter((h) => !ours(h && h.command, hook));
+      removed += before - group.hooks.length;
+      return group.hooks.length > 0 || before === 0;
+    });
+    if (!map[ev].length) delete map[ev];
+  }
+  return removed;
+}
+
+// `{ <event>: [entry] }` (Kete Code, Cursor).
+function removeFlat(map, hook) {
+  let removed = 0;
+  for (const ev of Object.keys(map || {})) {
+    if (!Array.isArray(map[ev])) continue;
+    const kept = map[ev].filter((h) => !ours(h && h.command, hook));
+    removed += map[ev].length - kept.length;
+    if (kept.length) map[ev] = kept;
+    else delete map[ev];
+  }
+  return removed;
+}
+
+function grouped(host, timeoutUnit = 1) {
+  return {
+    add: (data, cmd, hook, event) => {
+      const [ev, matcher] = EVENTS[host][event];
+      const entry = { type: 'command', command: cmd, timeout: TIMEOUT_S[event] * timeoutUnit };
+      if (host === 'gemini') entry.name = `kete-loom-${hook}`;
+      ((data.hooks ||= {})[ev] ||= []).push({ ...(matcher ? { matcher } : {}), hooks: [entry] });
+    },
+    remove: (data, hook) => removeGrouped(data.hooks, hook),
+  };
+}
+
+const pascal = (s) => s.replace(/(^|-)(\w)/g, (_, __, c) => c.toUpperCase());
+
+const HOSTS = {
+  claude: { file: (home) => path.join(home, '.claude', 'settings.json'), ...grouped('claude') },
+  codex: {
+    standalone: true,
+    file: (home) => path.join(home, '.codex', 'hooks.json'),
+    ...grouped('codex'),
+    note: 'Codex runs a new or changed hook only after you trust it: open Codex and run /hooks.',
+  },
+  // Gemini CLI timeouts are milliseconds.
+  gemini: { file: (home) => path.join(home, '.gemini', 'settings.json'), ...grouped('gemini', 1000) },
+  kete: {
+    // Kete Code reads kete.json and kete.jsonc; edit the one that exists, preferring .jsonc.
+    file: (home) => {
+      const dir = path.join(home, '.config', 'kete');
+      const jsonc = path.join(dir, 'kete.jsonc');
+      return fs.existsSync(jsonc) ? jsonc : path.join(dir, 'kete.json');
+    },
+    add: (data, cmd, hook, event) => {
+      const [ev, match] = EVENTS.kete[event];
+      (((data.kete ||= {}).hooks ||= {})[ev] ||= []).push({ ...(match ? { match } : {}), command: cmd, timeout: TIMEOUT_S[event] });
+    },
+    remove: (data, hook) => removeFlat(data.kete && data.kete.hooks, hook),
+  },
+  cursor: {
+    standalone: true,
+    file: (home) => path.join(home, '.cursor', 'hooks.json'),
+    add: (data, cmd, hook, event) => {
+      data.version ||= 1;
+      ((data.hooks ||= {})[EVENTS.cursor[event][0]] ||= []).push({ command: cmd, timeout: TIMEOUT_S[event] });
+    },
+    remove: (data, hook) => removeFlat(data.hooks, hook),
+  },
+  copilot: {
+    own: true,
+    file: (home, hook) => path.join(process.env.COPILOT_HOME || path.join(home, '.copilot'), 'hooks', `kete-loom-${hook}.json`),
+    content: (cmd, hook, event) =>
+      JSON.stringify({ version: 1, hooks: { [EVENTS.copilot[event][0]]: [{ type: 'command', bash: cmd, powershell: `& ${cmd}`, timeoutSec: TIMEOUT_S[event] }] } }, null, 2) + '\n',
+    isOurs: (text, hook) => {
+      try {
+        return Object.values(JSON.parse(text).hooks).some((list) => list.some((h) => ours(h.bash, hook)));
+      } catch {
+        return false;
+      }
+    },
+  },
+  opencode: {
+    own: true,
+    file: (home, hook) => path.join(home, '.config', 'opencode', 'plugins', `kete-loom-${hook}.js`),
+    // OpenCode hooks are plugins: hand the raw call to the shared runner, and throw to block.
+    content: (cmd, hook, event, home, node = process.execPath) => {
+      const key = EVENTS.opencode[event][0];
+      const before = key === 'tool.execute.before';
+      return `// kete-loom hook ${hook} (${event}): generated by \`npx @ketecode/loom install --hook ${hook}\`; remove with uninstall.
+// runner: ${cmd}
+import { spawnSync } from "node:child_process"
+
+export const KeteLoom${pascal(hook)} = async ({ directory }) => ({
+  ${JSON.stringify(key)}: async (input, output) => {
+    const r = spawnSync(${JSON.stringify(node)}, [${JSON.stringify(path.join(runtimeDir(home), 'run.js'))}, "opencode", ${JSON.stringify(hook)}, ${JSON.stringify(event)}], {
+      input: JSON.stringify({ tool: input && input.tool, args: (output && output.args) || (input && input.args), cwd: directory }),
+      encoding: "utf8",
+      timeout: ${TIMEOUT_S[event] * 1000},
+    })${before ? '\n    if (r.status === 2) throw new Error((r.stderr || "").trim() || "Blocked by kete-loom")' : ''}
+  },
+})
+`;
+    },
+    isOurs: (text, hook) => ours((/^\/\/ runner: (.*)$/m.exec(text) || [])[1], hook),
+  },
+};
+
+const HOOK_HOSTS = Object.keys(HOSTS);
+const supports = (host, event) => Boolean(EVENTS[host] && EVENTS[host][event]);
+
+class CommentedFileError extends Error {}
+
+// After removing our entries, drop the containers they leave empty (`hooks: {}`, `kete: {}`).
+function prune(data) {
+  const empty = (v) => v && typeof v === 'object' && !Array.isArray(v) && !Object.keys(v).length;
+  if (data.kete && empty(data.kete.hooks)) delete data.kete.hooks;
+  if (empty(data.kete)) delete data.kete;
+  if (empty(data.hooks)) delete data.hooks;
+  return data;
+}
+
+function readJson(file) {
+  if (!fs.existsSync(file)) return {};
+  const text = fs.readFileSync(file, 'utf8');
+  if (!text.trim()) return {};
+  try {
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('top level is not an object');
+    return data;
+  } catch (e) {
+    // shortcut: comment detection is a strip-and-retry, not a JSONC parser; fine for telling the cases apart.
+    const stripped = text.replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (m, str) => str || '');
+    try {
+      JSON.parse(stripped.replace(/,(\s*[}\]])/g, '$1'));
+    } catch {
+      throw new Error(`${file} isn't valid JSON (${e.message}); not touching it`);
+    }
+    throw new CommentedFileError(`${file} has comments, and rewriting it would drop them`);
+  }
+}
+
+function writeAtomic(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.kete-loom-backup`);
+  const tmp = `${file}.kete-loom-tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, file);
+}
+
+function snippet(host, cmd, hook, event) {
+  const data = {};
+  HOSTS[host].add(data, cmd, hook, event);
+  return JSON.stringify(data, null, 2);
+}
+
+// Registers one hook with one host. Returns { action, dest, reason?, note? }.
+function register(host, hook, event, { home, dryRun = false, node = process.execPath }) {
+  const h = HOSTS[host];
+  if (!supports(host, event)) return { action: 'skipped', dest: h.file(home, hook), reason: `${host} has no ${event} hook` };
+  const cmd = command(home, host, hook, event, node);
+  const file = h.file(home, hook);
+  if (h.own) {
+    const exists = fs.existsSync(file);
+    if (exists && !h.isOurs(fs.readFileSync(file, 'utf8'), hook)) return { action: 'skipped', dest: file, reason: 'a file with this name exists and was not written by kete-loom' };
+    if (!dryRun) writeAtomic(file, h.content(cmd, hook, event, home, node));
+    return { action: exists ? 'updated' : 'installed', dest: file, note: h.note };
+  }
+  let data;
+  try {
+    data = readJson(file);
+  } catch (e) {
+    const reason = e instanceof CommentedFileError ? `${e.message}. Add this yourself:\n${snippet(host, cmd, hook, event)}` : e.message;
+    return { action: 'skipped', dest: file, reason };
+  }
+  const existed = h.remove(data, hook) > 0;
+  h.add(data, cmd, hook, event);
+  if (!dryRun) writeAtomic(file, JSON.stringify(data, null, 2) + '\n');
+  return { action: existed ? 'updated' : 'installed', dest: file, note: h.note };
+}
+
+// Removes one hook (or every kete-loom hook when `hook` is null) from one host.
+function unregister(host, hook, { home, dryRun = false, names = [] }) {
+  const h = HOSTS[host];
+  if (h.own) {
+    const removed = [];
+    for (const name of hook ? [hook] : names) {
+      const file = h.file(home, name);
+      if (fs.existsSync(file) && h.isOurs(fs.readFileSync(file, 'utf8'), name)) {
+        if (!dryRun) fs.rmSync(file);
+        removed.push({ name, dest: file });
+      }
+    }
+    return removed;
+  }
+  const file = h.file(home, hook);
+  if (!fs.existsSync(file)) return [];
+  let data;
+  try {
+    data = readJson(file);
+  } catch {
+    return []; // not ours to fix
+  }
+  const before = registered(host, { home });
+  if (!h.remove(data, hook)) return [];
+  prune(data);
+  if (!dryRun) {
+    // A standalone hooks file holding nothing but its version is deleted rather than left behind.
+    if (h.standalone && !Object.keys(data).filter((k) => k !== 'version').length) fs.rmSync(file);
+    else writeAtomic(file, JSON.stringify(data, null, 2) + '\n');
+  }
+  return before.filter((name) => !hook || name === hook).map((name) => ({ name, dest: file }));
+}
+
+// Names of kete-loom hooks registered with a host.
+function registered(host, { home, names = [] }) {
+  const h = HOSTS[host];
+  if (h.own) return names.filter((n) => fs.existsSync(h.file(home, n)) && h.isOurs(fs.readFileSync(h.file(home, n), 'utf8'), n));
+  let data;
+  try {
+    data = readJson(h.file(home));
+  } catch {
+    return [];
+  }
+  const found = new Set();
+  (function walk(v) {
+    if (typeof v === 'string') {
+      const m = RUNNER_RE.exec(v);
+      if (m) found.add(m[2]);
+    } else if (v && typeof v === 'object') Object.values(v).forEach(walk);
+  })(data);
+  return [...found];
+}
+
+// Copies run.js and each hook's hook.js into ~/.kete-loom/hooks.
+function installRuntime(hooks, { home, dryRun = false, sourceDir }) {
+  if (dryRun) return;
+  const dir = runtimeDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.copyFileSync(path.join(sourceDir, 'run.js'), path.join(dir, 'run.js'));
+  for (const hook of hooks) {
+    fs.mkdirSync(path.join(dir, hook.dir), { recursive: true });
+    fs.copyFileSync(path.join(hook.path, 'hook.js'), path.join(dir, hook.dir, 'hook.js'));
+  }
+}
+
+module.exports = { HOSTS, HOOK_HOSTS, EVENTS, supports, register, unregister, registered, installRuntime, runtimeDir, command, ours, readJson, writeAtomic, CommentedFileError };

package/scripts/lib/i18n.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Translated READMEs (docs/i18n/README.<lang>.md) translate the English README's prose. The generated
+// catalog tables stay English-only, so the hash below ignores them: a translation is only out of date
+// when the prose it was made from changes.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const I18N_DIR = path.join(REPO_ROOT, 'docs', 'i18n');
+const LANGUAGES = {
+  ar: 'العربية',
+  de: 'Deutsch',
+  es: 'Español',
+  fr: 'Français',
+  ja: '日本語',
+  'pt-BR': 'Português (Brasil)',
+  sw: 'Kiswahili',
+  'zh-CN': '简体中文',
+};
+// The searchable catalog site, deployed by .github/workflows/pages.yml.
+const SITE_URL = 'https://kete-org.github.io/kete-loom/';
+const SOURCE_RE = /<!-- translated from README\.md, source ([0-9a-f]{12}) -->/;
+const GENERATED_RE = /(<!-- (\w+):start -->)[\s\S]*?(<!-- \2:end -->)/g;
+const SWITCHER_RE = /<!-- languages:start -->[\s\S]*?<!-- languages:end -->/;
+
+// The English prose with generated tables and the language switcher emptied.
+const prose = (text) => text.replace(SWITCHER_RE, '').replace(GENERATED_RE, '$1$3');
+const sourceHash = (text = fs.readFileSync(path.join(REPO_ROOT, 'README.md'), 'utf8')) =>
+  crypto.createHash('sha256').update(prose(text)).digest('hex').slice(0, 12);
+
+const switcher = (from = '') =>
+  `<!-- languages:start -->\n<p align="center">${[['README.md', 'English'], ...Object.entries(LANGUAGES).map(([code, label]) => [`docs/i18n/README.${code}.md`, label])]
+    .map(([file, label]) => `<a href="${path.posix.relative(from || '.', file)}">${label}</a>`)
+    .join(' · ')} · <a href="${SITE_URL}">Browse the catalog ↗</a></p>\n<!-- languages:end -->`;
+
+// Each translation that exists: its language and whether it matches the current English prose.
+function translations() {
+  const current = sourceHash();
+  return Object.keys(LANGUAGES)
+    .map((code) => ({ code, file: path.join(I18N_DIR, `README.${code}.md`) }))
+    .filter((t) => fs.existsSync(t.file))
+    .map((t) => {
+      const m = SOURCE_RE.exec(fs.readFileSync(t.file, 'utf8'));
+      return { ...t, source: m && m[1], current: Boolean(m) && m[1] === current };
+    });
+}
+
+module.exports = { LANGUAGES, I18N_DIR, sourceHash, prose, switcher, translations, SOURCE_RE, SWITCHER_RE };

package/scripts/lib/inventory.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// What kete-loom has installed, where, and at which version, read from the markers it writes:
+// `.kete-loom.json` in skill folders, `kete-loom name@version` comments in agents, commands and rules,
+// and the host configs for hooks, linked rules and MCP servers. `update` and `outdated` build on it.
+
+const fs = require('fs');
+const path = require('path');
+const { TARGETS, KINDS, resolveTarget } = require('./targets');
+const Hooks = require('./hooks-install');
+const Rules = require('./rules-install');
+const Mcp = require('./mcp-install');
+
+const FILE_MARKER = /^(?:# |<!-- )kete-loom ([a-z0-9-]+)@([^\s>]+)/m;
+
+function head(file) {
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(512);
+    const n = fs.readSync(fd, buf, 0, 512, 0);
+    fs.closeSync(fd);
+    return buf.toString('utf8', 0, n);
+  } catch {
+    return '';
+  }
+}
+
+function skillEntry(dir, entry) {
+  const p = path.join(dir, entry);
+  let stat;
+  try {
+    stat = fs.lstatSync(p);
+  } catch {
+    return null;
+  }
+  if (stat.isSymbolicLink()) return { name: entry, version: null, linked: true, path: p };
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(p, '.kete-loom.json'), 'utf8'));
+    return { name: entry, version: marker.version || null, path: p };
+  } catch {
+    return null; // not installed by kete-loom
+  }
+}
+
+// Rows of { target, kind, name, version, path, linked? } for one scope.
+function inventory({ scope = 'user', home, cwd = process.cwd(), mcpAll = Mcp.listMcp(), hookNames = [] }) {
+  const rows = [];
+  for (const target of Object.keys(TARGETS)) {
+    for (const kind of KINDS) {
+      const dir = resolveTarget(target, { scope, home, cwd, kind });
+      if (!dir || !fs.existsSync(dir)) continue;
+      for (const entry of fs.readdirSync(dir)) {
+        if (kind === 'skills') {
+          const s = skillEntry(dir, entry);
+          if (s) rows.push({ target, kind, ...s });
+          continue;
+        }
+        const m = FILE_MARKER.exec(head(path.join(dir, entry)));
+        if (m) rows.push({ target, kind, name: m[1], version: m[2], path: path.join(dir, entry) });
+      }
+    }
+  }
+  if (scope === 'user') {
+    for (const host of Rules.RULE_HOSTS) {
+      const dir = Rules.HOSTS[host].dir(home);
+      for (const name of Rules.installedNames(dir)) {
+        const m = FILE_MARKER.exec(head(path.join(dir, `${name}.md`)));
+        rows.push({ target: host, kind: 'rules', name, version: m ? m[2] : null, path: path.join(dir, `${name}.md`) });
+      }
+    }
+    for (const host of Hooks.HOOK_HOSTS) for (const name of Hooks.registered(host, { home, names: hookNames })) rows.push({ target: host, kind: 'hooks', name, version: null });
+  }
+  for (const host of Mcp.MCP_HOSTS) for (const name of Mcp.registeredMcp(host, mcpAll, { scope, home, cwd })) rows.push({ target: host, kind: 'mcp', name, version: null });
+  return rows;
+}
+
+// -1, 0 or 1 for two x.y.z versions.
+function compare(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
+  return 0;
+}
+
+module.exports = { inventory, compare };

package/scripts/lib/lint.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// The spec rules for a single item (docs/SKILL_SPEC.md). Shipped with the CLI so `kete-loom check` can
+// lint skills, agents, commands, rules and hooks you write yourself; scripts/lint-skills.js adds the
+// repository-wide checks on top.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { TOOLS } = require('./render');
+const { loadBehavior } = require('./behavior');
+
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const TOP_KEYS = new Set(['name', 'description', 'license', 'compatibility', 'metadata']);
+const CATEGORIES = ['coding', 'testing', 'security', 'integrations', 'devops', 'data', 'ai', 'docs', 'business', 'compliance', 'meta'];
+const RISKS = ['read-only', 'writes-files', 'runs-commands', 'network'];
+const MAX_LINES = 300;
+const MIN_EVALS = 3;
+const HOOK_EVENTS = ['pre-shell', 'pre-edit', 'post-edit', 'session-start', 'stop', 'stop-gate'];
+const MAX_RULE_LINES = 80;
+// Tool names that only exist in one host. Skills should describe the action instead.
+const HOST_SPECIFIC = /\b(Bash tool|Read tool|Edit tool|Write tool|Grep tool|Glob tool|TodoWrite|apply_patch|str_replace_editor)\b/;
+
+function words(s) {
+  return new Set(String(s).toLowerCase().match(/[a-z]{4,}/g) || []);
+}
+
+function jaccard(a, b) {
+  const inter = [...a].filter((x) => b.has(x)).length;
+  return inter / (a.size + b.size - inter || 1);
+}
+
+function lintItem(item) {
+  const errors = [...item.parseErrors];
+  const warnings = [];
+  const d = item.data;
+  const meta = d.metadata && typeof d.metadata === 'object' ? d.metadata : null;
+
+  for (const key of Object.keys(d)) if (!TOP_KEYS.has(key)) errors.push(`unknown top-level key "${key}" (put host-specific keys under metadata)`);
+
+  if (!d.name) errors.push('missing "name"');
+  else {
+    if (!NAME_RE.test(d.name)) errors.push(`name "${d.name}" must match ${NAME_RE}`);
+    if (d.name.length > 64) errors.push('name longer than 64 characters');
+    if (d.name !== item.dir) errors.push(`name "${d.name}" must equal ${item.kind === 'command' ? 'file' : 'folder'} name "${item.dir}"`);
+  }
+
+  if (!d.description) errors.push('missing "description"');
+  else if (item.kind === 'command' || item.kind === 'hook' || item.kind === 'rule') {
+    // Commands are picked by name and hooks run on events; the description is one line for menus and the catalog.
+    const len = d.description.length;
+    if (len < 20 || len > 300) errors.push(`description is ${len} chars; must be 20-300`);
+  } else {
+    const len = d.description.length;
+    if (len < 80 || len > 1024) errors.push(`description is ${len} chars; must be 80-1024`);
+    if (!/\buse when\b/i.test(d.description)) errors.push(`description must say when to use the ${item.kind} ("Use when ...")`);
+  }
+
+  if (!d.license) errors.push('missing "license"');
+  if (d.compatibility && d.compatibility.length > 500) errors.push('compatibility longer than 500 characters');
+
+  if (!meta) errors.push('missing "metadata" map');
+  else {
+    const v = meta['kete-loom/version'];
+    if (!v) errors.push('missing metadata.kete-loom/version');
+    else if (!SEMVER_RE.test(v)) errors.push(`kete-loom/version "${v}" is not semver`);
+    const c = meta['kete-loom/category'];
+    if (!CATEGORIES.includes(c)) errors.push(`kete-loom/category must be one of ${CATEGORIES.join(', ')}`);
+    const r = meta['kete-loom/risk'];
+    if (!RISKS.includes(r)) errors.push(`kete-loom/risk must be one of ${RISKS.join(', ')}`);
+    if (item.tools) {
+      const bad = item.tools.filter((t) => !TOOLS.includes(t));
+      if (bad.length || !item.tools.length) errors.push(`kete-loom/tools must be a comma list of ${TOOLS.join(', ')}`);
+    }
+  }
+
+  const lines = item.text.replace(/\r?\n$/, '').split('\n').length;
+  if (lines > MAX_LINES) errors.push(`${path.basename(item.file)} is ${lines} lines; limit is ${MAX_LINES}. Move detail into references/.`);
+
+  // Every relative file the body points at must exist.
+  const refs = new Set();
+  for (const m of item.body.matchAll(/\]\((?!https?:|#|mailto:)([^)\s]+)\)/g)) refs.add(m[1]);
+  for (const m of item.body.matchAll(/`((?:references|scripts|assets|templates)\/[^`\s]+)`/g)) refs.add(m[1]);
+  for (const ref of refs) {
+    if (!fs.existsSync(path.join(item.kind === 'command' ? path.dirname(item.path) : item.path, ref.split('#')[0]))) errors.push(`referenced file not found: ${ref}`);
+  }
+
+  const scriptsDir = path.join(item.path, 'scripts');
+  if (fs.existsSync(scriptsDir)) {
+    for (const f of fs.readdirSync(scriptsDir)) {
+      const p = path.join(scriptsDir, f);
+      const head = fs.readFileSync(p, 'utf8').slice(0, 2);
+      if (head === '#!' && !(fs.statSync(p).mode & 0o111) && process.platform !== 'win32') errors.push(`scripts/${f} has a shebang but is not executable (chmod +x)`);
+    }
+  }
+
+  if (item.kind === 'hook') errors.push(...lintHook(item));
+  // Rules load into every matching session, so they stay short: the always-on cost is paid on every turn.
+  if (item.kind === 'rule' && lines > MAX_RULE_LINES) errors.push(`rule is ${lines} lines; rules are loaded into context automatically, keep them under ${MAX_RULE_LINES}`);
+  if (item.kind === 'rule' && item.paths.some((p) => /\s/.test(p) || p.startsWith('/'))) errors.push('kete-loom/paths must be relative globs without spaces, comma separated (e.g. "**/*.py, **/*.pyi")');
+
+  // Hosts route to skills and agents by description, so both need trigger evals. Commands and hooks aren't routed.
+  const evalFile = ['command', 'hook', 'rule'].includes(item.kind) ? null : path.join(item.path, 'evals', 'triggers.json');
+  if (evalFile && !fs.existsSync(evalFile)) errors.push('missing evals/triggers.json');
+  else if (evalFile) {
+    try {
+      const ev = JSON.parse(fs.readFileSync(evalFile, 'utf8'));
+      for (const k of ['should_trigger', 'should_not_trigger']) {
+        if (!Array.isArray(ev[k]) || ev[k].length < MIN_EVALS) errors.push(`evals/triggers.json needs at least ${MIN_EVALS} "${k}" prompts`);
+      }
+    } catch (e) {
+      errors.push(`evals/triggers.json is not valid JSON: ${e.message}`);
+    }
+  }
+
+  // Behaviour evals are optional; when present they must be runnable.
+  if (item.kind === 'skill' || item.kind === 'agent') {
+    const behavior = loadBehavior(item);
+    if (behavior) errors.push(...behavior.problems);
+  }
+
+  const hostHit = HOST_SPECIFIC.exec(item.body);
+  if (hostHit) warnings.push(`mentions host-specific tool "${hostHit[1]}"; describe the action instead so every host can follow it`);
+
+  return { errors, warnings };
+}
+
+// A hook ships hook.js (exports check). Blocking (pre-*) hooks also ship cases.json, and every case must
+// give the expected verdict; a case is a command string or an event object such as { files: [...] }.
+function lintHook(hook) {
+  const errors = [];
+  if (!HOOK_EVENTS.includes(hook.event)) errors.push(`kete-loom/event must be one of ${HOOK_EVENTS.join(', ')}`);
+  let check;
+  try {
+    ({ check } = require(path.join(hook.path, 'hook.js')));
+  } catch (e) {
+    return [...errors, `hook.js failed to load: ${e.message}`];
+  }
+  if (typeof check !== 'function') return [...errors, 'hook.js must export a check(event) function'];
+  if (!String(hook.event).startsWith('pre-')) return errors;
+  let cases;
+  try {
+    // Fake secrets are written as {{repeat:c:n}} so the repository never holds key-shaped strings.
+    cases = JSON.parse(fs.readFileSync(path.join(hook.path, 'cases.json'), 'utf8').replace(/\{\{repeat:(.):(\d+)\}\}/g, (_, c, n) => c.repeat(Number(n))));
+  } catch (e) {
+    return [...errors, `cases.json missing or invalid: ${e.message}`];
+  }
+  // Hooks that remember what they've seen keep it under KETE_LOOM_STATE_DIR; give each lint run a fresh one.
+  const prevState = process.env.KETE_LOOM_STATE_DIR;
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kete-loom-lint-'));
+  process.env.KETE_LOOM_STATE_DIR = stateDir;
+  try {
+    lintCases(check, cases, errors);
+  } finally {
+    if (prevState === undefined) delete process.env.KETE_LOOM_STATE_DIR;
+    else process.env.KETE_LOOM_STATE_DIR = prevState;
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+  return errors;
+}
+
+function lintCases(check, cases, errors) {
+  for (const [key, want] of [['should_block', true], ['should_allow', false]]) {
+    if (!Array.isArray(cases[key]) || cases[key].length < MIN_EVALS) errors.push(`cases.json needs at least ${MIN_EVALS} "${key}" cases`);
+    for (const c of cases[key] || []) {
+      const event = typeof c === 'string' ? { command: c, cwd: process.cwd() } : { cwd: process.cwd(), ...c };
+      let got;
+      try {
+        got = Boolean(check(event).block);
+      } catch (e) {
+        errors.push(`check() threw on ${JSON.stringify(c)}: ${e.message}`);
+        continue;
+      }
+      if (got !== want) errors.push(`case ${JSON.stringify(c)} should ${want ? 'block' : 'be allowed'}`);
+    }
+  }
+}
+
+module.exports = { lintItem, lintHook, words, jaccard, NAME_RE, SEMVER_RE, CATEGORIES, RISKS, MAX_LINES, HOOK_EVENTS };