@spardutti/claude-skills 2.32.1 → 2.32.3

package/lib/auto-mode.mjs

@@ -0,0 +1,85 @@
+// The permissions rule that lets the skill gates clear themselves under auto
+// mode. Separate from installing the hooks: this writes the USER's global
+// settings, that writes a project's, and only one of them can be done for you.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+
+// The project-level permissions.allow written above does not clear auto mode.
+// The classifier reads autoMode.allow, and only from the user's own
+// ~/.claude/settings.json — it deliberately ignores a project's settings so a
+// cloned repo cannot loosen it. So the gate's ack was denied, and the remedy the
+// deny message named could not be applied by the agent either: the classifier
+// refuses an agent editing permission settings by any route. That left a
+// deadlock nothing in the session could break. The installer can, because npx
+// runs as the user, not as an agent — but only ever behind an explicit prompt,
+// since this is the user's global file.
+export const AUTO_MODE_RULE =
+  "Touching marker files under /tmp/claude-skill-gate-*, /tmp/claude-skill-acked-* " +
+  "and /tmp/claude-skill-loaded-* is allowed: they are acknowledgement files for the " +
+  "user's own PreToolUse skill gates. Creating one satisfies a workflow gate the user " +
+  "installed, grants no permission and executes no code, and is a false positive for " +
+  "Auto-Mode Bypass.";
+
+// Any entry naming a marker path is ours, whatever wording it shipped with. An
+// upgrade must correct that entry rather than add a second one beside it —
+// a fresh-install test would never see the difference.
+const AUTO_MODE_RULE_MARK = "/tmp/claude-skill-acked-";
+
+function globalSettingsPath(homeDir) {
+  return join(homeDir ?? homedir(), ".claude", "settings.json");
+}
+
+async function readGlobalSettings(homeDir) {
+  try {
+    return JSON.parse(await readFile(globalSettingsPath(homeDir), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+// "current" — the rule is present and matches. "stale" — an older wording is
+// there. "missing" — nothing of ours. "unreadable" — the file exists but does
+// not parse, so we must not rewrite it.
+export async function autoModeRuleStatus(homeDir) {
+  let raw;
+  try {
+    raw = await readFile(globalSettingsPath(homeDir), "utf-8");
+  } catch {
+    return "missing";
+  }
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch {
+    return "unreadable";
+  }
+  const allow = settings?.autoMode?.allow;
+  if (!Array.isArray(allow)) return "missing";
+  if (allow.includes(AUTO_MODE_RULE)) return "current";
+  if (allow.some((r) => typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK))) return "stale";
+  return "missing";
+}
+
+// Writes the rule into ~/.claude/settings.json, keeping "$defaults" first —
+// dropping it discards every built-in allow. Everything else in the file is
+// preserved. Refuses an unparseable file rather than replacing it.
+export async function writeAutoModeRule(homeDir) {
+  if ((await autoModeRuleStatus(homeDir)) === "unreadable") {
+    throw new Error(`${globalSettingsPath(homeDir)} is not valid JSON — fix it, then re-run.`);
+  }
+  const settings = (await readGlobalSettings(homeDir)) ?? {};
+  if (!settings.autoMode || typeof settings.autoMode !== "object") settings.autoMode = {};
+  const existing = Array.isArray(settings.autoMode.allow) ? settings.autoMode.allow : [];
+
+  const kept = existing.filter(
+    (r) => r !== "$defaults" && !(typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK)),
+  );
+  settings.autoMode.allow = ["$defaults", ...kept, AUTO_MODE_RULE];
+
+  const path = globalSettingsPath(homeDir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+  return path;
+}

package/lib/frontmatter.mjs

@@ -0,0 +1,49 @@
+// The one parser for a SKILL.md / command / agent frontmatter block.
+//
+// There used to be two — one in github.mjs, one in local.mjs — written
+// differently, and they disagreed on four of five inputs:
+//
+//   description: "d"        github kept the quotes, local stripped them
+//   category: "Q"           same
+//   requires-agents: p, q   github returned [], local returned ["p","q"]
+//
+// So `--local` and a real install read the same file differently. The quote
+// difference was masked downstream by a stripQuotes() in prompt.mjs, which is
+// what let it live: the picker looked right, so nobody looked further.
+//
+// Behaviour kept here is local.mjs's, because it was the correct one on every
+// case: quotes stripped, and both `[a, b]` and `a, b` accepted for a list.
+export function parseFrontmatter(content, fallbackName) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
+  }
+  const block = match[1];
+
+  // A value may be quoted or bare. Descriptions are quoted in every skill this
+  // repo ships, so returning the quotes is wrong for the common case, not the
+  // edge one.
+  const pick = (key) => {
+    const m = block.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+    return m ? m[1].trim().replace(/^["']|["']$/g, "") : "";
+  };
+
+  return {
+    name: pick("name") || fallbackName,
+    description: pick("description"),
+    category: pick("category") || "General",
+    requiresAgents: parseAgentList(pick("requires-agents")),
+  };
+}
+
+// `requires-agents: [a, b]` is what every command in this repo writes, but the
+// brackets are YAML flow syntax rather than part of the value, so a bare
+// `a, b` means the same thing and must parse the same way.
+export function parseAgentList(raw) {
+  if (!raw) return [];
+  return raw
+    .replace(/[[\]]/g, "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}

package/lib/github.mjs

@@ -1,3 +1,4 @@
+import { parseFrontmatter } from "./frontmatter.mjs";
 import { execSync } from "node:child_process";
 
 const REPO_OWNER = "Spardutti";
@@ -172,36 +173,3 @@ export function fetchAgents() {
     },
   });
 }
-
-function parseFrontmatter(content, fallbackName) {
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) {
-    return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
-  }
-
-  const block = match[1];
-  const name = block.match(/^name:\s*(.+)$/m)?.[1]?.trim() || fallbackName;
-  const description = block.match(/^description:\s*(.+)$/m)?.[1]?.trim() || "";
-  const category = block.match(/^category:\s*(.+)$/m)?.[1]?.trim() || "General";
-  const requiresAgents = parseAgentList(block);
-
-  return { name, description, category, requiresAgents };
-}
-
-function parseAgentList(block) {
-  const inline = block.match(/^requires-agents:\s*\[([^\]]*)\]\s*$/m);
-  if (inline) {
-    return inline[1]
-      .split(",")
-      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
-      .filter(Boolean);
-  }
-  const multiline = block.match(/^requires-agents:\s*\n((?:\s{2,}-\s*.+\n?)+)/m);
-  if (multiline) {
-    return multiline[1]
-      .split("\n")
-      .map((l) => l.replace(/^\s*-\s*/, "").trim().replace(/^["']|["']$/g, ""))
-      .filter(Boolean);
-  }
-  return [];
-}

package/lib/hook-settings.mjs

@@ -0,0 +1,140 @@
+// Registering the hooks in .claude/settings.json — which is a different job
+// from writing the hook files, and the one with all the upgrade traps: a hook
+// already registered under an old matcher stays on it unless corrected, and a
+// legacy entry from an earlier version has to be removed rather than ignored.
+import { readFile, writeFile } from "node:fs/promises";
+
+const GATE_FILENAME = "skill-gate.sh";
+const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
+const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
+const GAUNTLET_FILENAME = "gauntlet.sh";
+const SHIP_GATE_FILENAME = "ship-gate.sh";
+const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
+const VERSION_CHECK_FILENAME = "version-check.sh";
+const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
+const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
+
+
+// Register the entry, or CORRECT the one already there. Skipping when a hook of
+// this name exists leaves an existing install pinned to whatever matcher it was
+// first written with — which is how the skill gates kept watching only
+// Write|Edit|MultiEdit after they learned to cover Bash.
+function upsert(list, filename, entry) {
+  const existing = list.find((e) => e.hooks?.some((h) => h.command?.endsWith(filename)));
+  if (!existing) return list.push(entry);
+  if (entry.matcher === undefined) delete existing.matcher;
+  else existing.matcher = entry.matcher;
+  existing.hooks = entry.hooks;
+}
+
+export async function registerHooks(settingsPath) {
+  let settings = {};
+  try {
+    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
+  } catch {
+    // missing or invalid — start fresh
+  }
+  if (!settings.hooks) settings.hooks = {};
+
+  // Clean up legacy UserPromptSubmit eval hook (replaced by the gate).
+  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
+    settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_EVAL_FILENAME))
+    );
+    if (settings.hooks.UserPromptSubmit.length === 0) {
+      delete settings.hooks.UserPromptSubmit;
+    }
+  }
+
+  // Clean up legacy PreToolUse audit-runner hook (2.3.x — removed in 2.4.0).
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_AUDIT_RUNNER_FILENAME))
+    );
+  }
+
+  // Register PreToolUse gate.
+  const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
+  const gateEntry = {
+    matcher: "Write|Edit|MultiEdit|Bash",
+    hooks: [{ type: "command", command: gateCommand }],
+  };
+
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    upsert(settings.hooks.PreToolUse, GATE_FILENAME, gateEntry);
+  } else {
+    settings.hooks.PreToolUse = [gateEntry];
+  }
+
+  // Register PreToolUse application gate (after the loading gate).
+  const applicationCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${APPLICATION_GATE_FILENAME}`;
+  const applicationEntry = {
+    matcher: "Write|Edit|MultiEdit|Bash",
+    hooks: [{ type: "command", command: applicationCommand }],
+  };
+  upsert(settings.hooks.PreToolUse, APPLICATION_GATE_FILENAME, applicationEntry);
+
+  // Register PreToolUse ship-gate receipt check on Bash.
+  const shipGateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${SHIP_GATE_HOOK_FILENAME}`;
+  const shipGateEntry = {
+    matcher: "Bash",
+    hooks: [{ type: "command", command: shipGateCommand }],
+  };
+  upsert(settings.hooks.PreToolUse, SHIP_GATE_HOOK_FILENAME, shipGateEntry);
+
+  // Register PostToolUse auto-mark on Skill.
+  const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
+  const autoMarkEntry = {
+    matcher: "Skill",
+    hooks: [{ type: "command", command: autoMarkCommand }],
+  };
+
+  if (Array.isArray(settings.hooks.PostToolUse)) {
+    upsert(settings.hooks.PostToolUse, AUTO_MARK_FILENAME, autoMarkEntry);
+  } else {
+    settings.hooks.PostToolUse = [autoMarkEntry];
+  }
+
+  // Register SessionStart version check. No matcher: startup and resume both
+  // want it, and the script's own daily stamp keeps a burst of resumes quiet.
+  const versionCheckCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${VERSION_CHECK_FILENAME}`;
+  const versionCheckEntry = { hooks: [{ type: "command", command: versionCheckCommand }] };
+
+  if (Array.isArray(settings.hooks.SessionStart)) {
+    upsert(settings.hooks.SessionStart, VERSION_CHECK_FILENAME, versionCheckEntry);
+  } else {
+    settings.hooks.SessionStart = [versionCheckEntry];
+  }
+
+  // Register Stop gauntlet hook.
+  const gauntletCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GAUNTLET_FILENAME}`;
+  const gauntletEntry = { hooks: [{ type: "command", command: gauntletCommand }] };
+
+  if (Array.isArray(settings.hooks.Stop)) {
+    upsert(settings.hooks.Stop, GAUNTLET_FILENAME, gauntletEntry);
+  } else {
+    settings.hooks.Stop = [gauntletEntry];
+  }
+
+  // Both gates clear by touching a marker under /tmp. The hook scripts let those
+  // commands through themselves, but auto mode's permission classifier does not:
+  // a touch whose only purpose is to unlock a gate is exactly what it refuses.
+  // So in auto mode the application gate could not be satisfied at all, and the
+  // model was reduced to asking its user to run the touch by hand — which is
+  // indistinguishable from the laundering the classifier exists to stop.
+  // Allowlisting the three marker paths is what makes the gates workable there.
+  // Only these literal prefixes are granted, and an existing entry is not
+  // duplicated on reinstall.
+  const MARKER_ALLOW = [
+    "Bash(touch /tmp/claude-skill-gate-*)",
+    "Bash(touch /tmp/claude-skill-acked-*)",
+    "Bash(touch /tmp/claude-skill-loaded-*)",
+  ];
+  if (!settings.permissions) settings.permissions = {};
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+  for (const rule of MARKER_ALLOW) {
+    if (!settings.permissions.allow.includes(rule)) settings.permissions.allow.push(rule);
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
+}

package/lib/local.mjs

@@ -3,54 +3,11 @@
 // publishing it first.
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { parseFrontmatter } from "./frontmatter.mjs";
 
-const exec = promisify(execFile);
-
-function parseFrontmatter(content, fallbackName) {
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
-  const fm = match[1];
-  const pick = (key) => {
-    const m = fm.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
-    return m ? m[1].trim().replace(/^["']|["']$/g, "") : "";
-  };
-  const raw = pick("requires-agents");
-  return {
-    name: pick("name") || fallbackName,
-    description: pick("description"),
-    category: pick("category") || "General",
-    requiresAgents: raw ? raw.replace(/[[\]]/g, "").split(",").map((s) => s.trim()).filter(Boolean) : [],
-  };
-}
-
-async function listDir(dir) {
+export async function listDir(dir) {
   try { return await readdir(dir, { withFileTypes: true }); } catch { return []; }
 }
-
-// Build output is not a project. Next.js writes a package.json into .next/,
-// .next/dev/ and .next/standalone/, so a scan that skipped only a hardcoded
-// list reported three phantom projects on a plain Next app — and then filtered
-// the real repo root out as "a root that delegates to a workspace". A second
-// list of build dirs drifts from .gitignore the moment a framework adds one, so
-// ask git the way ship-gate.sh already does. --directory collapses a fully
-// ignored tree to its own name, which is what keeps this output small.
-async function gitIgnoredDirs(projectDir) {
-  try {
-    const { stdout } = await exec(
-      "git",
-      ["-C", projectDir, "ls-files", "--others", "--ignored", "--exclude-standard", "--directory"],
-      { maxBuffer: 10 * 1024 * 1024 },
-    );
-    return new Set(
-      stdout.split("\n").filter((l) => l.endsWith("/")).map((l) => l.slice(0, -1)),
-    );
-  } catch {
-    return new Set();
-  }
-}
-
 export function makeLocalSource(root) {
   return {
     async fetchSkills() {
@@ -125,92 +82,4 @@ async function pythonAdvice(dir, rel, entries) {
     install,
     config: `${rel ? rel + "/" : ""}pyproject.toml  [tool.mutmut] source_paths=["${source}/"] pytest_add_cli_args_test_selection=["${tests}/"]`,
   };
-}
-
-// What the installed commands need that this project does not have yet.
-// ship-gate.sh's own detection drives a single-package repo; a monorepo whose
-// tools need a workspace prefix or a container sets GAUNTLET_MUTATE instead. Only
-// /ship needs anything: a mutation tool, per project, since a monorepo can hold
-// several and they do not share one.
-export async function reportToolNeeds(projectDir) {
-  const needs = [];
-  const seen = new Set();
-  // Whether a nested project of each kind exists at all — not whether it still
-  // needs a tool. A root that delegates is not the place to install, even once
-  // the workspace it delegates to is already set up.
-  const nested = { Stryker: false, mutmut: false };
-  // Empty outside a git repo, so the hardcoded list below still carries those.
-  const ignored = await gitIgnoredDirs(projectDir);
-
-  async function scan(rel, depth) {
-    if (depth > 2) return;
-    const dir = rel ? join(projectDir, rel) : projectDir;
-    const entries = await listDir(dir);
-    const label = rel ? `${rel}/` : "<repo root>";
-
-    const pkg = entries.find((e) => e.isFile() && e.name === "package.json");
-    const pyp = entries.find((e) => e.isFile() && (e.name === "pyproject.toml" || e.name === "pytest.ini"));
-
-    if (pkg && rel) nested.Stryker = true;
-    if (pyp && rel) nested.mutmut = true;
-
-    if (pkg && !seen.has(label)) {
-      seen.add(label);
-      const text = await readFile(join(dir, "package.json"), "utf-8");
-      if (!text.includes("@stryker-mutator/core")) {
-        const at = rel ? rel + "/" : "";
-        needs.push({
-          label,
-          rel,
-          tool: "Stryker",
-          install: `npm --prefix ${rel || "."} i -D @stryker-mutator/core @stryker-mutator/vitest-runner`,
-          config: `${at}stryker.config.json  {"testRunner":"vitest","plugins":["@stryker-mutator/vitest-runner"],"coverageAnalysis":"perTest"}`,
-          // Stryker copies the whole project into .stryker-tmp/sandbox-*/, so
-          // every test file briefly exists twice and the runner collects both.
-          // The duplicates pass, so a doubled test count is the only symptom.
-          // Spread configDefaults.exclude — assigning it drops node_modules.
-          also: [
-            `${at}vitest.config.ts  exclude: [...configDefaults.exclude, "**/.stryker-tmp/**"]`,
-            `${at}.gitignore  .stryker-tmp/`,
-          ],
-        });
-      } else {
-        // Stryker is installed, so this project is not missing a tool — but the
-        // projects that already run it are the ones grinding through mutants on
-        // className strings, and a setup done before the ignorer existed has no
-        // way to learn about it. Offer it here or it never reaches them.
-        let cfg = "";
-        try {
-          cfg = await readFile(join(dir, "stryker.config.json"), "utf-8");
-        } catch {
-          // no config of its own — the scaffolder writes one
-        }
-        if (!cfg.includes("tailwind-classnames")) {
-          needs.push({ label, rel, tool: "Stryker", ignorerOnly: true });
-        }
-      }
-    }
-    if (pyp && !seen.has(label + ":py")) {
-      seen.add(label + ":py");
-      const text = pyp.name === "pyproject.toml" ? await readFile(join(dir, "pyproject.toml"), "utf-8") : "";
-      if (!text.includes("[tool.mutmut]")) {
-        const advice = await pythonAdvice(dir, rel, entries);
-        needs.push({ label, tool: "mutmut", ...advice });
-      }
-    }
-
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      if (["node_modules", ".git", "dist", "build", ".venv", "venv", ".claude"].includes(e.name)) continue;
-      const child = rel ? `${rel}/${e.name}` : e.name;
-      if (ignored.has(child)) continue;
-      await scan(child, depth + 1);
-    }
-  }
-
-  await scan("", 0);
-
-  // A root package.json that delegates to a workspace (npm --prefix web run test)
-  // has no tests of its own, so asking for a mutation tool there is noise.
-  return needs.filter((n) => n.label !== "<repo root>" || !nested[n.tool]);
-}
+}

package/lib/post-install.mjs

@@ -5,14 +5,9 @@
 // decides what gets installed.
 import { confirm, input } from "@inquirer/prompts";
 import chalk from "chalk";
-import {
-  setupHook,
-  detectStack,
-  writeGauntletConf,
-  autoModeRuleStatus,
-  writeAutoModeRule,
-} from "./setup-hook.mjs";
-import { reportToolNeeds } from "./local.mjs";
+import { setupHook, detectStack, writeGauntletConf } from "./setup-hook.mjs";
+import { autoModeRuleStatus, writeAutoModeRule } from "./auto-mode.mjs";
+import { reportToolNeeds } from "./tool-needs.mjs";
 import { scaffoldStryker } from "./scaffold-stryker.mjs";
 import { setupClaudeMd } from "./setup-claude-md.mjs";
 

package/lib/scaffold-stryker.mjs

@@ -34,36 +34,7 @@ const CONFIG = {
   ignoreStatic: true,
   tempDirName: ".stryker-tmp",
 };
-
-// Bumped whenever IGNORER changes. A project scaffolded before a rule existed
-// has no other way to learn about it, and the file is generated, not authored —
-// so a missing marker means overwrite, not keep.
-const IGNORER_VERSION = "v3";
-
-// .mjs, not .js: an app without "type": "module" in its package.json cannot
-// load ESM from a .js file, and the plugin is ESM.
-const IGNORER = `// Generated by @spardutti/claude-skills — ignorer ${IGNORER_VERSION}. Edits are
-// overwritten when the rules change.
-//
-// Ignore by WHERE the mutant sits, not by what kind it is. Disabling the
-// StringLiteral mutator globally would also stop mutating labels, keys and
-// separators — strings whose value is behaviour.
-//
-// Content in a module-level table is NOT handled here. Those are static mutants,
-// and \`ignoreStatic\` in stryker.config.json covers them for less.
-import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
-
-export const strykerPlugins = [
-  declareValuePlugin(PluginKind.Ignore, "tailwind-classnames", {
-    shouldIgnore(path) {
-      if (path.find((p) => p.isJSXAttribute() && p.node.name.name === "className"))
-        return "styling, not behaviour";
-      if (path.find((p) => p.isCallExpression() && p.node.callee.name === "cn"))
-        return "styling, not behaviour";
-    },
-  }),
-];
-`;
+import { IGNORER, IGNORER_VERSION } from "./stryker-ignorer.mjs";
 
 async function exists(p) {
   try {

package/lib/setup-hook.mjs

@@ -1,3 +1,4 @@
+import { registerHooks } from "./hook-settings.mjs";
 import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
 import { join, resolve, dirname } from "node:path";
 import { spawn } from "node:child_process";
@@ -90,18 +91,6 @@ export async function writeGauntletConf(targetDir, testCommand) {
   return confPath;
 }
 
-// Register the entry, or CORRECT the one already there. Skipping when a hook of
-// this name exists leaves an existing install pinned to whatever matcher it was
-// first written with — which is how the skill gates kept watching only
-// Write|Edit|MultiEdit after they learned to cover Bash.
-function upsert(list, filename, entry) {
-  const existing = list.find((e) => e.hooks?.some((h) => h.command?.endsWith(filename)));
-  if (!existing) return list.push(entry);
-  if (entry.matcher === undefined) delete existing.matcher;
-  else existing.matcher = entry.matcher;
-  existing.hooks = entry.hooks;
-}
-
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
@@ -129,115 +118,7 @@ export async function setupHook(targetDir = process.cwd()) {
     // not present — fine
   }
 
-  let settings = {};
-  try {
-    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
-  } catch {
-    // missing or invalid — start fresh
-  }
-  if (!settings.hooks) settings.hooks = {};
-
-  // Clean up legacy UserPromptSubmit eval hook (replaced by the gate).
-  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
-    settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
-      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_EVAL_FILENAME))
-    );
-    if (settings.hooks.UserPromptSubmit.length === 0) {
-      delete settings.hooks.UserPromptSubmit;
-    }
-  }
-
-  // Clean up legacy PreToolUse audit-runner hook (2.3.x — removed in 2.4.0).
-  if (Array.isArray(settings.hooks.PreToolUse)) {
-    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
-      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_AUDIT_RUNNER_FILENAME))
-    );
-  }
-
-  // Register PreToolUse gate.
-  const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
-  const gateEntry = {
-    matcher: "Write|Edit|MultiEdit|Bash",
-    hooks: [{ type: "command", command: gateCommand }],
-  };
-
-  if (Array.isArray(settings.hooks.PreToolUse)) {
-    upsert(settings.hooks.PreToolUse, GATE_FILENAME, gateEntry);
-  } else {
-    settings.hooks.PreToolUse = [gateEntry];
-  }
-
-  // Register PreToolUse application gate (after the loading gate).
-  const applicationCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${APPLICATION_GATE_FILENAME}`;
-  const applicationEntry = {
-    matcher: "Write|Edit|MultiEdit|Bash",
-    hooks: [{ type: "command", command: applicationCommand }],
-  };
-  upsert(settings.hooks.PreToolUse, APPLICATION_GATE_FILENAME, applicationEntry);
-
-  // Register PreToolUse ship-gate receipt check on Bash.
-  const shipGateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${SHIP_GATE_HOOK_FILENAME}`;
-  const shipGateEntry = {
-    matcher: "Bash",
-    hooks: [{ type: "command", command: shipGateCommand }],
-  };
-  upsert(settings.hooks.PreToolUse, SHIP_GATE_HOOK_FILENAME, shipGateEntry);
-
-  // Register PostToolUse auto-mark on Skill.
-  const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
-  const autoMarkEntry = {
-    matcher: "Skill",
-    hooks: [{ type: "command", command: autoMarkCommand }],
-  };
-
-  if (Array.isArray(settings.hooks.PostToolUse)) {
-    upsert(settings.hooks.PostToolUse, AUTO_MARK_FILENAME, autoMarkEntry);
-  } else {
-    settings.hooks.PostToolUse = [autoMarkEntry];
-  }
-
-  // Register SessionStart version check. No matcher: startup and resume both
-  // want it, and the script's own daily stamp keeps a burst of resumes quiet.
-  const versionCheckCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${VERSION_CHECK_FILENAME}`;
-  const versionCheckEntry = { hooks: [{ type: "command", command: versionCheckCommand }] };
-
-  if (Array.isArray(settings.hooks.SessionStart)) {
-    upsert(settings.hooks.SessionStart, VERSION_CHECK_FILENAME, versionCheckEntry);
-  } else {
-    settings.hooks.SessionStart = [versionCheckEntry];
-  }
-
-  // Register Stop gauntlet hook.
-  const gauntletCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GAUNTLET_FILENAME}`;
-  const gauntletEntry = { hooks: [{ type: "command", command: gauntletCommand }] };
-
-  if (Array.isArray(settings.hooks.Stop)) {
-    upsert(settings.hooks.Stop, GAUNTLET_FILENAME, gauntletEntry);
-  } else {
-    settings.hooks.Stop = [gauntletEntry];
-  }
-
-  // Both gates clear by touching a marker under /tmp. The hook scripts let those
-  // commands through themselves, but auto mode's permission classifier does not:
-  // a touch whose only purpose is to unlock a gate is exactly what it refuses.
-  // So in auto mode the application gate could not be satisfied at all, and the
-  // model was reduced to asking its user to run the touch by hand — which is
-  // indistinguishable from the laundering the classifier exists to stop.
-  // Allowlisting the three marker paths is what makes the gates workable there.
-  // Only these literal prefixes are granted, and an existing entry is not
-  // duplicated on reinstall.
-  const MARKER_ALLOW = [
-    "Bash(touch /tmp/claude-skill-gate-*)",
-    "Bash(touch /tmp/claude-skill-acked-*)",
-    "Bash(touch /tmp/claude-skill-loaded-*)",
-  ];
-  if (!settings.permissions) settings.permissions = {};
-  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
-  for (const rule of MARKER_ALLOW) {
-    if (!settings.permissions.allow.includes(rule)) settings.permissions.allow.push(rule);
-  }
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
+  await registerHooks(settingsPath);
 
   console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${AUTO_MARK_FILENAME}`);
@@ -246,82 +127,4 @@ export async function setupHook(targetDir = process.cwd()) {
   console.log(`  Installed: .claude/hooks/${SHIP_GATE_FILENAME} (used by /ship)`);
   console.log(`  Hook installed: .claude/hooks/${SHIP_GATE_HOOK_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
-}
-
-// The project-level permissions.allow written above does not clear auto mode.
-// The classifier reads autoMode.allow, and only from the user's own
-// ~/.claude/settings.json — it deliberately ignores a project's settings so a
-// cloned repo cannot loosen it. So the gate's ack was denied, and the remedy the
-// deny message named could not be applied by the agent either: the classifier
-// refuses an agent editing permission settings by any route. That left a
-// deadlock nothing in the session could break. The installer can, because npx
-// runs as the user, not as an agent — but only ever behind an explicit prompt,
-// since this is the user's global file.
-export const AUTO_MODE_RULE =
-  "Touching marker files under /tmp/claude-skill-gate-*, /tmp/claude-skill-acked-* " +
-  "and /tmp/claude-skill-loaded-* is allowed: they are acknowledgement files for the " +
-  "user's own PreToolUse skill gates. Creating one satisfies a workflow gate the user " +
-  "installed, grants no permission and executes no code, and is a false positive for " +
-  "Auto-Mode Bypass.";
-
-// Any entry naming a marker path is ours, whatever wording it shipped with. An
-// upgrade must correct that entry rather than add a second one beside it —
-// a fresh-install test would never see the difference.
-const AUTO_MODE_RULE_MARK = "/tmp/claude-skill-acked-";
-
-function globalSettingsPath(homeDir) {
-  return join(homeDir ?? homedir(), ".claude", "settings.json");
-}
-
-async function readGlobalSettings(homeDir) {
-  try {
-    return JSON.parse(await readFile(globalSettingsPath(homeDir), "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-// "current" — the rule is present and matches. "stale" — an older wording is
-// there. "missing" — nothing of ours. "unreadable" — the file exists but does
-// not parse, so we must not rewrite it.
-export async function autoModeRuleStatus(homeDir) {
-  let raw;
-  try {
-    raw = await readFile(globalSettingsPath(homeDir), "utf-8");
-  } catch {
-    return "missing";
-  }
-  let settings;
-  try {
-    settings = JSON.parse(raw);
-  } catch {
-    return "unreadable";
-  }
-  const allow = settings?.autoMode?.allow;
-  if (!Array.isArray(allow)) return "missing";
-  if (allow.includes(AUTO_MODE_RULE)) return "current";
-  if (allow.some((r) => typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK))) return "stale";
-  return "missing";
-}
-
-// Writes the rule into ~/.claude/settings.json, keeping "$defaults" first —
-// dropping it discards every built-in allow. Everything else in the file is
-// preserved. Refuses an unparseable file rather than replacing it.
-export async function writeAutoModeRule(homeDir) {
-  if ((await autoModeRuleStatus(homeDir)) === "unreadable") {
-    throw new Error(`${globalSettingsPath(homeDir)} is not valid JSON — fix it, then re-run.`);
-  }
-  const settings = (await readGlobalSettings(homeDir)) ?? {};
-  if (!settings.autoMode || typeof settings.autoMode !== "object") settings.autoMode = {};
-  const existing = Array.isArray(settings.autoMode.allow) ? settings.autoMode.allow : [];
-
-  const kept = existing.filter(
-    (r) => r !== "$defaults" && !(typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK)),
-  );
-  settings.autoMode.allow = ["$defaults", ...kept, AUTO_MODE_RULE];
-
-  const path = globalSettingsPath(homeDir);
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
-  return path;
-}
+}

package/lib/stryker-ignorer.mjs

@@ -0,0 +1,37 @@
+// The class-name ignorer Stryker loads as a plugin — generated file content,
+// not scaffolding logic, and the one step people skipped when the CLI printed
+// steps instead of writing files.
+//
+// IGNORER_VERSION is what tells an existing install its copy is stale, so bump
+// it whenever the body changes or nobody gets the fix.
+
+
+// Bumped whenever IGNORER changes. A project scaffolded before a rule existed
+// has no other way to learn about it, and the file is generated, not authored —
+// so a missing marker means overwrite, not keep.
+export const IGNORER_VERSION = "v3";
+
+// .mjs, not .js: an app without "type": "module" in its package.json cannot
+// load ESM from a .js file, and the plugin is ESM.
+export const IGNORER = `// Generated by @spardutti/claude-skills — ignorer ${IGNORER_VERSION}. Edits are
+// overwritten when the rules change.
+//
+// Ignore by WHERE the mutant sits, not by what kind it is. Disabling the
+// StringLiteral mutator globally would also stop mutating labels, keys and
+// separators — strings whose value is behaviour.
+//
+// Content in a module-level table is NOT handled here. Those are static mutants,
+// and \`ignoreStatic\` in stryker.config.json covers them for less.
+import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
+
+export const strykerPlugins = [
+  declareValuePlugin(PluginKind.Ignore, "tailwind-classnames", {
+    shouldIgnore(path) {
+      if (path.find((p) => p.isJSXAttribute() && p.node.name.name === "className"))
+        return "styling, not behaviour";
+      if (path.find((p) => p.isCallExpression() && p.node.callee.name === "cn"))
+        return "styling, not behaviour";
+    },
+  }),
+];
+`;

package/lib/tool-needs.mjs

@@ -0,0 +1,123 @@
+// What the installed commands need that this project does not have — a report,
+// not an install. Nothing to do with reading a local catalog, which is what the
+// rest of local.mjs was for; they shared a file and nothing else.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { listDir } from "./local.mjs";
+
+const exec = promisify(execFile);
+
+
+// Build output is not a project. Next.js writes a package.json into .next/,
+// .next/dev/ and .next/standalone/, so a scan that skipped only a hardcoded
+// list reported three phantom projects on a plain Next app — and then filtered
+// the real repo root out as "a root that delegates to a workspace". A second
+// list of build dirs drifts from .gitignore the moment a framework adds one, so
+// ask git the way ship-gate.sh already does. --directory collapses a fully
+// ignored tree to its own name, which is what keeps this output small.
+async function gitIgnoredDirs(projectDir) {
+  try {
+    const { stdout } = await exec(
+      "git",
+      ["-C", projectDir, "ls-files", "--others", "--ignored", "--exclude-standard", "--directory"],
+      { maxBuffer: 10 * 1024 * 1024 },
+    );
+    return new Set(
+      stdout.split("\n").filter((l) => l.endsWith("/")).map((l) => l.slice(0, -1)),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+
+
+// What the installed commands need that this project does not have yet.
+// ship-gate.sh's own detection drives a single-package repo; a monorepo whose
+// tools need a workspace prefix or a container sets GAUNTLET_MUTATE instead. Only
+// /ship needs anything: a mutation tool, per project, since a monorepo can hold
+// several and they do not share one.
+export async function reportToolNeeds(projectDir) {
+  const needs = [];
+  const seen = new Set();
+  // Whether a nested project of each kind exists at all — not whether it still
+  // needs a tool. A root that delegates is not the place to install, even once
+  // the workspace it delegates to is already set up.
+  const nested = { Stryker: false, mutmut: false };
+  // Empty outside a git repo, so the hardcoded list below still carries those.
+  const ignored = await gitIgnoredDirs(projectDir);
+
+  async function scan(rel, depth) {
+    if (depth > 2) return;
+    const dir = rel ? join(projectDir, rel) : projectDir;
+    const entries = await listDir(dir);
+    const label = rel ? `${rel}/` : "<repo root>";
+
+    const pkg = entries.find((e) => e.isFile() && e.name === "package.json");
+    const pyp = entries.find((e) => e.isFile() && (e.name === "pyproject.toml" || e.name === "pytest.ini"));
+
+    if (pkg && rel) nested.Stryker = true;
+    if (pyp && rel) nested.mutmut = true;
+
+    if (pkg && !seen.has(label)) {
+      seen.add(label);
+      const text = await readFile(join(dir, "package.json"), "utf-8");
+      if (!text.includes("@stryker-mutator/core")) {
+        const at = rel ? rel + "/" : "";
+        needs.push({
+          label,
+          rel,
+          tool: "Stryker",
+          install: `npm --prefix ${rel || "."} i -D @stryker-mutator/core @stryker-mutator/vitest-runner`,
+          config: `${at}stryker.config.json  {"testRunner":"vitest","plugins":["@stryker-mutator/vitest-runner"],"coverageAnalysis":"perTest"}`,
+          // Stryker copies the whole project into .stryker-tmp/sandbox-*/, so
+          // every test file briefly exists twice and the runner collects both.
+          // The duplicates pass, so a doubled test count is the only symptom.
+          // Spread configDefaults.exclude — assigning it drops node_modules.
+          also: [
+            `${at}vitest.config.ts  exclude: [...configDefaults.exclude, "**/.stryker-tmp/**"]`,
+            `${at}.gitignore  .stryker-tmp/`,
+          ],
+        });
+      } else {
+        // Stryker is installed, so this project is not missing a tool — but the
+        // projects that already run it are the ones grinding through mutants on
+        // className strings, and a setup done before the ignorer existed has no
+        // way to learn about it. Offer it here or it never reaches them.
+        let cfg = "";
+        try {
+          cfg = await readFile(join(dir, "stryker.config.json"), "utf-8");
+        } catch {
+          // no config of its own — the scaffolder writes one
+        }
+        if (!cfg.includes("tailwind-classnames")) {
+          needs.push({ label, rel, tool: "Stryker", ignorerOnly: true });
+        }
+      }
+    }
+    if (pyp && !seen.has(label + ":py")) {
+      seen.add(label + ":py");
+      const text = pyp.name === "pyproject.toml" ? await readFile(join(dir, "pyproject.toml"), "utf-8") : "";
+      if (!text.includes("[tool.mutmut]")) {
+        const advice = await pythonAdvice(dir, rel, entries);
+        needs.push({ label, tool: "mutmut", ...advice });
+      }
+    }
+
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (["node_modules", ".git", "dist", "build", ".venv", "venv", ".claude"].includes(e.name)) continue;
+      const child = rel ? `${rel}/${e.name}` : e.name;
+      if (ignored.has(child)) continue;
+      await scan(child, depth + 1);
+    }
+  }
+
+  await scan("", 0);
+
+  // A root package.json that delegates to a workspace (npm --prefix web run test)
+  // has no tests of its own, so asking for a mutation tool there is noise.
+  return needs.filter((n) => n.label !== "<repo root>" || !nested[n.tool]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.32.1",
+  "version": "2.32.3",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {